REST · JSON · Bearer · OpenAPI 3.0
REST API for enterprise clients
The REST API that lets you wire quotes, orders, production status, deliveries and invoices into your own operations stack — ERP, customer portal, service desk. Documented in OpenAPI 3.0 with examples in curl, Python and Node.js. Access is granted to clients on an active programme with a signed usage agreement.
Basics: authentication, base URL, format
The API authenticates with a bearer token we issue to you with your programme. The token rotates every ninety days or on your request. The production base URL is https://api.corp-merch.com.mx/v1. The sandbox base URL is https://sandbox.api.corp-merch.com.mx/v1. The sandbox carries fictitious data and resets every Monday at midnight GMT-6.
The exchange format is JSON with UTF-8. Dates and times are handled in ISO 8601 with timezone — we prefer YYYY-MM-DDTHH:MM:SS-06:00 for CDMX time. Amounts are in MXN cents — to represent fifty pesos fifty centavos you send 5050. Country codes are ISO 3166-1 alpha-2 — MX for Mexico, US for United States, CA for Canada.
Main endpoints
The API exposes six endpoint blocks. The quotes block: POST /quotes to create a quote, GET /quotes/{id} for the detail, POST /quotes/{id}/approve to approve, POST /quotes/{id}/reject to reject with reason. The orders block: POST /orders to create an order from an approved quote, GET /orders/{id} for the detail, PATCH /orders/{id} to update allowed fields before production, POST /orders/{id}/cancel to cancel before production.
The status block: GET /orders/{id}/status for the full status, GET /orders/{id}/status/history for the timestamped history, GET /orders/{id}/documents for associated documents. The shipments block: GET /orders/{id}/shipments to list shipments, GET /shipments/{id} for the detail, POST /shipments/{id}/confirm to confirm receipt when the customer signs. The invoices block: GET /orders/{id}/invoices to list, GET /invoices/{id} for the detail with CFDI 4.0 XML and PDF. The catalogue block: GET /catalog/products to list products, GET /catalog/products/{id} for detail with prices and stock.
Example: creating a quote
To create a quote, send a POST request to /v1/quotes with the bearer token in the Authorization header and a JSON body with the products, quantities, decoration technique and lead times. The endpoint returns a quote identifier and the detail with prices in MXN cents before VAT, broken-down VAT, total and per-line lead time.
The minimum body for a quote includes a lines array with product_id, quantity, decoration with the technique — screen, dtf, embroidery, laser — and delivery_address with the full address. For lines with variable personalisation — joiner number, individual size — include the variables array per line. The quote is delivered within a minute when the catalogue recognises the product and the address falls within coverage.
Example: checking order status
To check status, send a GET to /v1/orders/{id}/status with the bearer token. The endpoint returns the current status — created, approved, in_production, quality_check, packed, shipped, delivered, invoiced, closed, canceled — and progress percentage per stage. The response includes the estimated delivery date based on the customer's and the workshop's calendar.
For runs with multiple stages — cutting, sewing, decoration, packing, shipping, delivery — the customer gets the breakdown per stage with progress percentage. When a stage slips, status returns the reason — raw material shortage, non-conformance, awaiting customer confirmation — and the updated estimated date. The integration stays consistent with the webhooks that fire on status changes.
Error handling and retries
Errors return standard HTTP codes — 400 for malformed request, 401 for missing or invalid token, 403 for resource not allowed, 404 for resource not found, 409 for state conflict, 422 for validation failure, 429 for rate exceeded, 500 for internal error. The error body includes code with the machine-readable code, message with the human-readable description and details with the array of fields in error where applicable.
The rate limit is sixty requests per minute per token and one thousand requests per hour per token. When the limit is exceeded, the endpoint returns 429 with the Retry-After header indicating seconds to wait. We implement exponential backoff on the client with jitter to avoid the thundering herd effect. For customers with higher volume we negotiate a higher limit at programme start.
Integration best practices
We recommend three practices. First, use the sandbox for development and testing before moving to production. The sandbox has fictitious data and resets every Monday. Second, subscribe to webhooks instead of polling status — webhooks fire on status change without the customer having to poll. Third, validate the HMAC SHA-256 signatures of webhooks before processing the body to confirm the webhook comes from the API.
For customers on serverless stacks, webhooks sign the body and are delivered with timestamp and event-identifier headers. The customer must validate the signature, the timestamp — within five minutes — and the identifier to avoid duplicates on retry. The full documentation includes a reference section with available events and body format.
Support and observability
For customers with production integration we assign a workshop technical lead who responds to integration questions within four business hours and joins pair programming sessions when required. The technical lead also handles incidents — missed webhook response, drift between portal and API, unexpected response questions.
The API publishes operational metrics — availability, p95 latency, error rate — on a status dashboard customers can subscribe to. For customers with strict SLA — banking, fintech, government — we deliver a dedicated dashboard with real-time metrics and a direct communication channel for critical incidents. The status page is accessible without authentication.
Request SDK access
If your technical team needs SDK access to integrate quotes, orders, status, deliveries or invoices with your operations stack, let's talk. We deliver the bearer token, sandbox access and full documentation in your format.
The REST API and SDK are delivered to clients on an active programme with a signed usage agreement. Documentation may update without prior notice; major versions are communicated with thirty days' notice. Corp-Merch.MX is a Mexican workshop for corporate merch; we operate independently.