> ## Documentation Index > Fetch the complete documentation index at: https://developers.cubbo.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a pick-and-ship order and buy its labels > Creates a pick-and-ship order and generates its carrier shipping labels in the same call, returning the labels instead of the order. Use it when your own warehouse packs the parcel and only needs Cubbo's carrier contract: you declare the physical packages (weight and dimensions) and Cubbo buys one label per package. Unlike `POST /orders`, the order is validated synchronously, the shipping method must be resolvable now, and the order is left packed with its labels ready to download. - Choose the carrier with exactly one of `shipping_method_id` (a Cubbo shipping method) or `integration_shipping_method` (the name of a shipping configuration of your integration). Sending both, or neither, is refused. - `products` is optional; lines are not picked from Cubbo stock, they only describe the content. Each SKU must exist in the store. - Every package is matched to the closest Cubbo package size by the larger of its real weight and its volumetric weight; if none fits, the request fails with `NO_COMPATIBLE_PACKAGE`. - Not available for stores where Cubbo issues fiscal invoices (for example Brazil): those answer `INVOICING_NOT_IMPLEMENTED`. - The order is always a consumer (D2C), paid, non cash-on-delivery order with zero prices. - Colombia: `shipping.city_code` works as in `POST /orders`, except that a code Cubbo does not know is refused with 422 `UNRECOGNIZED_CITY_CODE`, since the labels are generated now. - Duplicate protection works like `POST /orders`: 422 `ORDER_ALREADY_EXISTS` for an existing `order_number`, 409 `DUPLICATE_REQUEST_IN_FLIGHT` while another request for the same `order_number` is in progress. ## OpenAPI ````yaml /openapi.yaml post /orders/create-and-ship openapi: 3.1.0 info: title: Cubbo Clients API version: '1.0' summary: >- Orders, inventory, replenishments, returns, shipping and webhooks for Cubbo fulfillment. description: > The Cubbo Clients API connects your store, ERP or marketplace with Cubbo's fulfillment network. All endpoints except `POST /auth/token` require a bearer token; see the Authentication guide. Request and response bodies are JSON. Errors are JSON objects with an `error` key. contact: name: Cubbo integrations email: integraciones@cubbo.com servers: - url: https://api.cubbo.com/v1 description: Production security: - bearerAuth: [] tags: - name: Authentication description: Exchange client credentials for a bearer token. - name: Orders description: Create, update, hold, cancel and read sales orders. - name: Shipping labels description: Read the shipping labels generated for an order. - name: Inventory description: Products and stock per store. - name: Lots description: Lot-level inventory for products with expiration or batch tracking. - name: Reports description: Bulk reports for reconciliation. - name: Replenishments description: Inbound shipments to the warehouse. - name: Returns description: Returns and exchanges. - name: Stores description: Store provisioning and settings. - name: Shipping methods description: Available shipping methods, coverage and quotes. - name: Click and collect description: Pickup points and in-store pickup orders. paths: /orders/create-and-ship: post: tags: - Orders summary: Create a pick-and-ship order and buy its labels description: > Creates a pick-and-ship order and generates its carrier shipping labels in the same call, returning the labels instead of the order. Use it when your own warehouse packs the parcel and only needs Cubbo's carrier contract: you declare the physical packages (weight and dimensions) and Cubbo buys one label per package. Unlike `POST /orders`, the order is validated synchronously, the shipping method must be resolvable now, and the order is left packed with its labels ready to download. - Choose the carrier with exactly one of `shipping_method_id` (a Cubbo shipping method) or `integration_shipping_method` (the name of a shipping configuration of your integration). Sending both, or neither, is refused. - `products` is optional; lines are not picked from Cubbo stock, they only describe the content. Each SKU must exist in the store. - Every package is matched to the closest Cubbo package size by the larger of its real weight and its volumetric weight; if none fits, the request fails with `NO_COMPATIBLE_PACKAGE`. - Not available for stores where Cubbo issues fiscal invoices (for example Brazil): those answer `INVOICING_NOT_IMPLEMENTED`. - The order is always a consumer (D2C), paid, non cash-on-delivery order with zero prices. - Colombia: `shipping.city_code` works as in `POST /orders`, except that a code Cubbo does not know is refused with 422 `UNRECOGNIZED_CITY_CODE`, since the labels are generated now. - Duplicate protection works like `POST /orders`: 422 `ORDER_ALREADY_EXISTS` for an existing `order_number`, 409 `DUPLICATE_REQUEST_IN_FLIGHT` while another request for the same `order_number` is in progress. operationId: createAndShipOrder requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderCreateAndShipRequest' examples: basic: summary: Mexico, one package value: store_id: 1234 order_number: PS-0001 shipping_method_id: 12 shipping: first_name: Jaime last_name: Carrera phone: '5555555555' email: buyer@example.com address1: Av. Reforma 123 country: MX city: Ciudad de México province: CDMX zip_code: '06600' products: - sku: SKU-RED-M quantity: 1 packages: - weight_kg: 1.2 length_cm: 30 width_cm: 20 height_cm: 10 colombiaCityCode: summary: Colombia, with the DANE code of the city value: store_id: 1234 order_number: PS-0002 shipping_method_id: 56 shipping: first_name: Ana last_name: Gómez phone: '5555555555' email: buyer@example.com address1: 'Calle 100 # 10-20' country: CO city: Bogotá province: Bogotá, D.C. city_code: '11001' products: - sku: SKU-RED-M quantity: 1 packages: - weight_kg: 1.2 length_cm: 30 width_cm: 20 height_cm: 10 responses: '200': description: Order created and packed; one shipping label per requested package. content: application/json: schema: type: array items: $ref: '#/components/schemas/CreateAndShipLabel' example: - id: 778899 order_id: 987655 billing_file: null shipping_number: '1234567890' label_file: path: /rails/active_storage/blobs/redirect/abc123/label.pdf url: >- https://api.cubbo.com/rails/active_storage/blobs/redirect/abc123/label.pdf filename: label.pdf byte_size: 48213 content_type: application/pdf label_type: shipping tracking_url: https://carrier.example.com/track/1234567890 cubbo_tracking_url: https://tracking.cubbo.com/t/abc123 '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/DuplicateRequestInFlight' '422': description: >- Validation or business error. Most failures use the `error`/`code`/`context` shape. When the assembled order fails Cubbo's order validation the body is instead a list of field-level errors (`errors`), each with the offending `field` and a `code`. content: application/json: schema: oneOf: - $ref: '#/components/schemas/OrderCreateError' - $ref: '#/components/schemas/OrderFieldValidationError' examples: missingParam: value: error: Parameter packages is required code: null context: null nameTooShort: value: error: Parameter first_name cannot have length less than 3 code: null context: null packageWeightTooSmall: value: error: Parameter weight_kg cannot be less than 0.01 code: null context: null missingShippingMethod: value: error: >- provide either shipping_method_id or integration_shipping_method code: MISSING_SHIPPING_METHOD context: null bothShippingMethods: value: error: >- provide either shipping_method_id or integration_shipping_method, not both code: INVALID_SHIPPING_METHOD context: null missingZipCode: value: error: zip_code is required for this warehouse's country code: MISSING_ZIP_CODE context: null channelIntegrationNotFound: value: error: >- Channel integration for openapi not found, contact support. code: '' context: null orderAlreadyExists: value: error: >- order with order_number PS-0001 already exists with id 987655 code: ORDER_ALREADY_EXISTS context: order_id: 987655 productNotFound: value: error: Product SKU-UNKNOWN was not found in this store code: PRODUCT_NOT_FOUND context: null invoicingNotImplemented: summary: The store's country requires Cubbo-issued invoices value: error: Order requires an invoice to ship code: INVOICING_NOT_IMPLEMENTED context: null storeOrShippingMethodNotFound: summary: The store_id or shipping_method_id does not exist value: error: Couldn't find ShippingMethod with 'id'=999999 code: null context: null integrationShippingMethodNotFound: value: error: >- No shipping configuration found with name 'Express' for this integration code: MISSING_INTEGRATION_SHIPPING_METHOD context: null undeterminableShippingMethod: value: error: Unable to determine shipping method for order code: UNDETERMINABLE_SHIPPING_METHOD context: null noCompatiblePackage: value: error: >- No compatible package found for order id 987655. Contact support. code: NO_COMPATIBLE_PACKAGE context: null shippingCostUnavailable: summary: The shipping method has no tariff for the package weight value: error: >- Shipping cost not configured for the order's weight in the assigned shipping method code: SHIPPING_COST_UNAVAILABLE context: null storeBusinessModelUnset: value: error: Store 1234 has neither b2b nor d2c enabled code: store_business_model_unset context: store_id: 1234 b2b: false d2c: false orderValidationFailed: summary: >- Field-level validation errors (for example an international method on a domestic address) value: errors: - field: shipping_method code: NATIONAL_SHIPPING_METHOD_EXPECTED additional_info: {} - field: shipping_phone code: MISSING_SHIPPING_FIELD additional_info: {} unrecognizedCity: summary: >- Chile, a shipping.city that cannot be identified (the order is not created) value: errors: - field: shipping_city code: UNRECOGNIZED_CITY_OR_STATE additional_info: {} unrecognizedCityCode: summary: >- Colombia, a shipping.city_code Cubbo does not know (the order is not created) value: errors: - field: shipping_city_code code: UNRECOGNIZED_CITY_CODE additional_info: city_code: '99999' '500': description: >- Unexpected error (including carrier failures while buying the label). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unexpected error security: - bearerAuth: [] components: schemas: OrderCreateAndShipRequest: type: object required: - store_id - order_number - shipping - packages properties: store_id: type: integer description: Id of the store the order belongs to. example: 1234 order_number: type: string description: Your identifier for the order. Must be unique within the store. example: PS-0001 shipping_method_id: type: integer description: >- Id of a Cubbo shipping method. Get it from `GET /shipping-methods/quote`: each option in the response has a `shipping_method_id`. Exactly one of `shipping_method_id` or `integration_shipping_method` must be sent. Coverage for the destination is validated through the order validation (`errors` response). example: 12 integration_shipping_method: type: string description: >- Exact name of a shipping method you created in the Cubbo app, under **Integrations**, your Open API integration, **Shipping Methods** (field **Integration Delivery Method**). It must match character by character: the comparison is case-sensitive and does not trim spaces. Cubbo uses the shipping configuration assigned to that method to pick the carrier. See [Set up your integration](/guides/setup#3-configure-shipping-methods). Exactly one of `shipping_method_id` or `integration_shipping_method` must be sent. There is no fallback here: an unknown name returns 422 `MISSING_INTEGRATION_SHIPPING_METHOD`. example: Express shipping: $ref: '#/components/schemas/CreateAndShipShippingAddress' products: type: array description: >- Optional content description of the parcel; each SKU must exist in the store. items: $ref: '#/components/schemas/CreateAndShipProductLine' packages: type: array minItems: 1 description: Physical packages to label; one label is generated per entry. items: $ref: '#/components/schemas/CreateAndShipPackage' CreateAndShipLabel: type: object description: A shipping label generated by `POST /orders/create-and-ship`. properties: id: type: integer description: >- Shipping label id; use it with `GET /shipping-labels/{shipping_label_id}`. example: 778899 order_id: type: integer description: Id of the order that was created. example: 987655 billing_file: oneOf: - $ref: '#/components/schemas/LabelFile' - type: 'null' description: >- Carrier billing document when the carrier provides one; otherwise `null`. shipping_number: type: - string - 'null' description: Carrier tracking number. example: '1234567890' label_file: $ref: '#/components/schemas/LabelFile' label_type: type: string description: Kind of label, normally `shipping`. example: shipping tracking_url: type: - string - 'null' description: Carrier tracking page. example: https://carrier.example.com/track/1234567890 cubbo_tracking_url: type: - string - 'null' description: Cubbo tracking page for the order. example: https://tracking.cubbo.com/t/abc123 OrderCreateError: type: object description: Error body of `POST /orders` and `POST /orders/create-and-ship`. required: - error properties: error: type: string description: Human-readable message. example: order with order_number ORD-0001 already exists with id 987654 code: type: - string - 'null' description: >- Machine-readable code. `null` for parameter errors, empty string for business errors without a dedicated code; shipping-method lookups use the legacy codes `"404"` and `"400"`. example: ORDER_ALREADY_EXISTS context: type: - object - 'null' description: >- Extra data for some codes, for example `{order_id}` on `ORDER_ALREADY_EXISTS`. additionalProperties: true example: order_id: 987654 OrderFieldValidationError: type: object description: Field-level validation errors of an order. required: - errors properties: errors: type: array items: type: object required: - field - code properties: field: type: string description: Order field the error refers to. example: shipping_method code: type: string description: >- Validation code, for example `NATIONAL_SHIPPING_METHOD_EXPECTED`, `MISSING_SHIPPING_FIELD`, `SHIPPING_METHOD_HAS_NO_COVERAGE`, `UNRECOGNIZED_CITY_OR_STATE`, `UNRECOGNIZED_CITY_CODE`. example: NATIONAL_SHIPPING_METHOD_EXPECTED additional_info: type: object description: Extra details for the code, often empty. additionalProperties: true example: {} Error: type: object description: Error body returned by every failed request. required: - error properties: error: type: string description: >- Human-readable description of the failure. For `401` responses it is always `Unauthorized`. example: Parameter store_id is required message: type: string description: >- Present on `401` responses only; the reason the request was rejected. example: invalid token code: type: - string - 'null' description: >- Stable machine-readable code, present on some order, return and replenishment errors. example: ORDER_ALREADY_EXISTS context: type: - object - 'null' description: >- Extra data about the failure when available, for example the id of the conflicting order. additionalProperties: true example: order_id: 987654 CreateAndShipShippingAddress: type: object description: Recipient and delivery address. Billing data is copied from this block. required: - first_name - address1 - country - city - province properties: first_name: type: string minLength: 3 description: Recipient first name (at least 3 characters). example: Jaime last_name: type: string description: Recipient last name. example: Carrera phone: type: string description: >- Recipient phone number. Optional here, but most carriers require it (`MISSING_SHIPPING_FIELD` otherwise). example: '5555555555' email: type: string format: email description: Recipient email. example: buyer@example.com address1: type: string minLength: 3 description: Street and number (at least 3 characters). example: Av. Reforma 123 address2: type: string description: Additional address line. example: Piso 4 interior_number: type: string description: Interior or apartment number. example: 4B country: type: string minLength: 2 description: Country as an ISO 3166-1 alpha-2 code. example: MX city: type: string minLength: 2 description: City. example: Ciudad de México province: type: string minLength: 2 description: State or province. example: CDMX zip_code: type: string description: >- Postal code. Required when the warehouse is in Mexico (`MISSING_ZIP_CODE` otherwise). example: '06600' city_code: type: string description: >- Colombia: optional, the DANE (DIVIPOLA) code of the city, as in `POST /orders`. When sent, it decides the destination instead of `city` and `province`. The labels are generated in this same call, so a code Cubbo does not know is refused with 422 `UNRECOGNIZED_CITY_CODE`. In other countries it is stored as sent, but it does not change the destination. example: '11001' CreateAndShipProductLine: type: object required: - sku - quantity properties: sku: type: string description: SKU of a product registered in the store. example: SKU-RED-M quantity: type: integer description: Units of this SKU in the parcel. example: 1 CreateAndShipPackage: type: object required: - weight_kg - length_cm - width_cm - height_cm properties: weight_kg: type: number minimum: 0.01 description: Real weight of the package in kilograms. example: 1.2 length_cm: type: number minimum: 1 description: Length in centimetres. example: 30 width_cm: type: number minimum: 1 description: Width in centimetres. example: 20 height_cm: type: number minimum: 1 description: Height in centimetres. example: 10 LabelFile: type: object description: Downloadable file. An empty object when no file is attached. properties: path: type: string description: Path of the file relative to the API host. example: /rails/active_storage/blobs/redirect/abc123/label.pdf url: type: string format: uri description: Absolute download URL. example: >- https://api.cubbo.com/rails/active_storage/blobs/redirect/abc123/label.pdf filename: type: string description: File name. example: label.pdf byte_size: type: integer description: Size in bytes. example: 48213 content_type: type: string description: MIME type. example: application/pdf DuplicateRequestInFlightError: type: object required: - error - code properties: error: type: string description: Human-readable message naming the contended order number. example: >- another request for order ORD-0001 is already being processed, retry in 5 seconds code: type: string enum: - DUPLICATE_REQUEST_IN_FLIGHT description: Fixed code for this condition. example: DUPLICATE_REQUEST_IN_FLIGHT transaction_id: type: - string - 'null' description: >- Identifier of the request currently holding the lock; useful when contacting support. example: c0ffee00-0000-4000-8000-000000000001 transaction_key: type: - string - 'null' description: The lock key that was contended. example: api_create_orders:1234:ORD-0001 responses: Unauthorized: description: >- Missing or invalid token, wrong credentials, or no access to the requested store. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidToken: value: error: Unauthorized message: invalid token noHeader: value: error: Unauthorized message: no authorization header found storeNotAllowed: value: error: Unauthorized message: not allowed to show? this Store DuplicateRequestInFlight: description: >- Another request for the same order number is still being processed (or a previous one was interrupted; the lock expires on its own within a few minutes). Nothing was created by this request. Wait for the number of seconds in the `Retry-After` header and retry with the same payload; the retry converges on the real outcome. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 5 content: application/json: schema: $ref: '#/components/schemas/DuplicateRequestInFlightError' example: error: >- another request for order ORD-0001 is already being processed, retry in 5 seconds code: DUPLICATE_REQUEST_IN_FLIGHT transaction_id: c0ffee00-0000-4000-8000-000000000001 transaction_key: api_create_orders:1234:ORD-0001 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Token returned by `POST /auth/token`, sent as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.