> ## 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 replenishment > Announces an inbound shipment (replenishment) of products to one of your store's warehouses. Every line is identified by SKU; all SKUs must already exist in your Cubbo catalog for the store. The replenishment is created in status `REQUESTED`, or `WITHOUT_SCHEDULING` when the target warehouse books receiving appointments natively (you then schedule the appointment separately; the replenishment is not visible to the warehouse's capacity planning until it is scheduled). - `warehouse_id` is optional; when omitted the store's first assigned warehouse is used. When sent, the warehouse must be assigned to the store. - Each SKU may appear once. Two different SKUs that point to the same product are refused (except for certain marketplace integrations, where such lines are merged into one and their quantities are added; the first declared `unit_value` is kept, and two different declared values for the same product are refused). - `unit_value` (declared unit cost in the store currency) is optional and must be a plain decimal with at most 2 decimal places, greater than 0 and below the supported ceiling. When omitted, Cubbo falls back to the catalog price wherever a cost is needed (for example on the Brazilian NF-e of entry). - `lots` lets you declare, per SKU, the lots (batches) that will arrive and how many units belong to each. The lot quantities must add up to the line quantity, and the SKU must have a master-box configuration in Cubbo. These expected quantities per lot are what the variance report compares against. - `sell_ahead: true` makes the announced units sellable immediately (before they physically arrive). The warehouse must have a presale location configured; otherwise the request is refused and nothing is created. Sell-ahead replenishments cannot be updated afterwards. - `unique_external_reference: true` makes the call idempotent on `(store_id, external_reference)`: if a non-canceled replenishment with that reference already exists in the store, the API answers 422 with code `REPLENISHMENT_ALREADY_EXISTS` and the existing `replenishment_id` instead of creating a second one. Canceled replenishments do not count. Without the flag, repeated references are accepted (existing behavior). - `inventory_scope` / `is_b2b` decide which sales channel the received stock serves. Omit both to use the store's business model (D2C-only stores receive as `d2c`, B2B-only as `b2b`, and stores with both models as `shared`). A scope incompatible with the store's model is refused. - Brazil: if your store's NF-e (Nota Fiscal eletrônica, the Brazilian fiscal invoice) for inbound stock is issued by your own invoicing provider rather than by Cubbo, you must send `invoice` with the already-issued NF-e (XML and PDF, base64). If Cubbo issues the NF-e for your store, it is generated automatically after the replenishment is created; some marketplace-integrated stores need neither. ## OpenAPI ````yaml /openapi.yaml post /replenishments 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: /replenishments: post: tags: - Replenishments summary: Create a replenishment description: > Announces an inbound shipment (replenishment) of products to one of your store's warehouses. Every line is identified by SKU; all SKUs must already exist in your Cubbo catalog for the store. The replenishment is created in status `REQUESTED`, or `WITHOUT_SCHEDULING` when the target warehouse books receiving appointments natively (you then schedule the appointment separately; the replenishment is not visible to the warehouse's capacity planning until it is scheduled). - `warehouse_id` is optional; when omitted the store's first assigned warehouse is used. When sent, the warehouse must be assigned to the store. - Each SKU may appear once. Two different SKUs that point to the same product are refused (except for certain marketplace integrations, where such lines are merged into one and their quantities are added; the first declared `unit_value` is kept, and two different declared values for the same product are refused). - `unit_value` (declared unit cost in the store currency) is optional and must be a plain decimal with at most 2 decimal places, greater than 0 and below the supported ceiling. When omitted, Cubbo falls back to the catalog price wherever a cost is needed (for example on the Brazilian NF-e of entry). - `lots` lets you declare, per SKU, the lots (batches) that will arrive and how many units belong to each. The lot quantities must add up to the line quantity, and the SKU must have a master-box configuration in Cubbo. These expected quantities per lot are what the variance report compares against. - `sell_ahead: true` makes the announced units sellable immediately (before they physically arrive). The warehouse must have a presale location configured; otherwise the request is refused and nothing is created. Sell-ahead replenishments cannot be updated afterwards. - `unique_external_reference: true` makes the call idempotent on `(store_id, external_reference)`: if a non-canceled replenishment with that reference already exists in the store, the API answers 422 with code `REPLENISHMENT_ALREADY_EXISTS` and the existing `replenishment_id` instead of creating a second one. Canceled replenishments do not count. Without the flag, repeated references are accepted (existing behavior). - `inventory_scope` / `is_b2b` decide which sales channel the received stock serves. Omit both to use the store's business model (D2C-only stores receive as `d2c`, B2B-only as `b2b`, and stores with both models as `shared`). A scope incompatible with the store's model is refused. - Brazil: if your store's NF-e (Nota Fiscal eletrônica, the Brazilian fiscal invoice) for inbound stock is issued by your own invoicing provider rather than by Cubbo, you must send `invoice` with the already-issued NF-e (XML and PDF, base64). If Cubbo issues the NF-e for your store, it is generated automatically after the replenishment is created; some marketplace-integrated stores need neither. operationId: createReplenishment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReplenishmentCreateRequest' example: store_id: 1234 warehouse_id: 7 expected_arrived_at: '2026-11-02T15:00:00Z' notes: Pallet 2 contains fragile items external_reference: PO-0001 unique_external_reference: true sell_ahead: false inventory_scope: d2c products: - sku: SKU-RED-M quantity: 100 unit_value: '12.50' - sku: SKU-BOX-BLUE quantity: 48 lots: - lot_code: LOT-2026-01 quantity: 24 external_reference: LOT-REF-1 - lot_code: LOT-2026-02 quantity: 24 external_reference: LOT-REF-2 responses: '201': description: Replenishment created content: application/json: schema: $ref: '#/components/schemas/ReplenishmentSummary' example: id: 55001 status: REQUESTED store_id: 1234 notes: Pallet 2 contains fragile items created_at: '2026-10-12T14:03:11.512Z' expected_arrived_at: '2026-11-02T15:00:00.000Z' sell_ahead: false declared_value: null warehouse_id: 7 replenishment_products: - product_id: 9001 expected_quantity: 100 unit_value: '12.5' product: id: 9001 name: Red T-shirt M bar_code: '7501234567890' is_scannable: true product_codes: - id: 31001 sku: SKU-RED-M - product_id: 9002 expected_quantity: 48 unit_value: null product: id: 9002 name: Blue box bar_code: '7501234567891' is_scannable: true product_codes: - id: 31002 sku: SKU-BOX-BLUE warehouse: id: 7 name: Mexico City unique_code: MX-CDMX-1 address1: Av. Ejemplo 123 address2: null zip_code: '01000' city: Ciudad de México state: CDMX country: MX '401': $ref: '#/components/responses/Unauthorized' '422': description: > Validation or business error. Most errors are `{error}`. The duplicate-reference refusal (`unique_external_reference: true`) also carries `code` and `context.replenishment_id`. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/ReplenishmentAlreadyExistsError' examples: missingParam: value: error: Parameter products is required invalidScope: value: error: >- Parameter inventory_scope must be within ["d2c", "b2b", "shared"] lotQuantityMismatch: value: error: >- total quantity for SKU-BOX-BLUE (48) does not match sum of lot quantities (40) unitValueFormat: value: error: >- unit_value for SKU-RED-M must be a plain decimal number with at most 2 decimal places, such as 12.50 unitValueDecimals: value: error: unit_value for SKU-RED-M may have at most 2 decimal places unitValueOutOfRange: value: error: >- unit_value for SKU-RED-M is out of range (must be below 100000000000000) unitValueNotPositive: value: error: unit_value for SKU-RED-M must be greater than 0 unitValueConflict: value: error: >- unit_value conflict between SKU-RED-M and SKU-RED-M-ALT for the same product storeNotFound: value: error: Couldn't find Store with 'id'=1234 externalReferenceRequired: value: error: >- external_reference is required when unique_external_reference is true alreadyExists: value: error: >- replenishment with external_reference PO-0001 already exists with id 55001 code: REPLENISHMENT_ALREADY_EXISTS context: replenishment_id: 55001 warehouseNotFound: value: error: Couldn't find Warehouse with 'id'=7 warehouseNotAssigned: value: error: warehouse 7 is not assigned to this store invoiceRequired: value: error: '''invoice'' parameter is required for this store' skusNotUnique: value: error: provided skus are not unique skusNotFound: value: error: 'SKUs not found in cubbo: SKU-UNKNOWN-1, SKU-UNKNOWN-2' skusOfSameProduct: value: error: >- skus of same product were provided, make sure skus belong to different products. Skus of same product: [SKU-RED-M, SKU-RED-M-ALT] masterBoxMissing: value: error: master_box_quantity not found for product SKU-BOX-BLUE noPresaleLocation: value: error: Aborted, no PRESALE location found in warehouse id 7. scopeConflict: value: error: Store 1234 is D2C-only; cannot create a b2b receipt storeModelUnset: value: error: Store 1234 has neither b2b nor d2c enabled '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: schemas: ReplenishmentCreateRequest: type: object required: - store_id - products properties: store_id: type: integer description: Store that owns the stock. example: 1234 warehouse_id: type: integer description: >- Destination warehouse. Must be assigned to the store. Defaults to the store's first warehouse. example: 7 expected_arrived_at: type: string format: date-time description: Expected arrival date (ISO 8601). example: '2026-11-02T15:00:00Z' notes: type: string description: Free-text notes for the warehouse. example: Pallet 2 contains fragile items external_reference: type: string description: >- Your reference for the shipment (purchase order, transfer number...). example: PO-0001 unique_external_reference: type: boolean description: >- When `true`, `external_reference` is required and the create is idempotent per store on that reference (see endpoint description). default: false example: true sell_ahead: type: boolean description: >- When `true`, the announced units become sellable immediately. Such replenishments cannot be updated later. default: false example: false is_b2b: type: boolean description: >- Legacy way to choose the inventory scope: `true` is equivalent to `inventory_scope: b2b`, `false` to `d2c`. Ignored when `inventory_scope` is sent. example: false inventory_scope: type: string description: >- Which sales channel the received stock serves. `shared` is only valid for stores that operate both B2B and D2C. Omit to use the store's default. enum: - d2c - b2b - shared example: d2c products: type: array description: Lines to announce (at least one). minItems: 1 items: $ref: '#/components/schemas/ReplenishmentCreateProduct' invoice: $ref: '#/components/schemas/ReplenishmentCreateInvoice' ReplenishmentSummary: type: object description: Replenishment as returned by create and update. properties: id: type: integer description: >- Replenishment id; use it as `replenishment_id` on the other endpoints. example: 55001 status: $ref: '#/components/schemas/ReplenishmentStatus' store_id: type: integer description: Store the replenishment belongs to. example: 1234 notes: type: - string - 'null' description: Free-text notes for the warehouse. example: Pallet 2 contains fragile items created_at: type: string format: date-time description: Creation time. example: '2026-10-12T14:03:11.512Z' expected_arrived_at: type: - string - 'null' format: date-time description: Expected arrival date declared on creation. example: '2026-11-02T15:00:00.000Z' sell_ahead: type: - boolean - 'null' description: Whether the announced units were made sellable before arrival. example: false declared_value: type: - string - 'null' description: >- Declared total value of the shipment, as a decimal string; not settable through this API, so usually `null`. example: null warehouse_id: type: integer description: Destination warehouse id. example: 7 replenishment_products: type: array description: Announced lines. items: $ref: '#/components/schemas/ReplenishmentProduct' warehouse: $ref: '#/components/schemas/ReplenishmentWarehouse' 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 ReplenishmentAlreadyExistsError: type: object description: >- Returned by create when `unique_external_reference` is `true` and the reference is already in use in the store. properties: error: type: string description: Human-readable message. example: >- replenishment with external_reference PO-0001 already exists with id 55001 code: type: string description: Always `REPLENISHMENT_ALREADY_EXISTS`. example: REPLENISHMENT_ALREADY_EXISTS context: type: object properties: replenishment_id: type: integer description: Id of the existing replenishment holding the reference. example: 55001 ReplenishmentCreateProduct: type: object description: A line to announce. required: - sku - quantity properties: sku: type: string description: SKU registered in the store's catalog. Each SKU may appear once. example: SKU-RED-M quantity: type: integer description: >- Units announced. When `lots` is sent, it must equal the sum of the lot quantities. example: 100 unit_value: type: - number - string description: >- Optional declared unit cost in the store currency. Plain decimal (digits, optional dot and up to 2 decimals, e.g. `12.50` or `"12.50"`), greater than 0 and below the supported ceiling. Omit to leave the line without a declared cost. example: '12.50' lots: type: array description: >- Expected lots for this SKU. Requires a master-box configuration for the SKU in Cubbo; the quantities must add up to `quantity`. items: $ref: '#/components/schemas/ReplenishmentCreateLot' ReplenishmentCreateInvoice: type: object description: >- Already-issued NF-e of entry, required for Brazilian stores whose NF-e is issued by their own provider instead of Cubbo. required: - key - xml_base64 - pdf_base64 properties: key: type: string description: 44-digit NF-e access key. example: '00000000000000000000000000000000000000000000' operation_type: type: string description: >- Whether the document is incoming or outgoing from the issuer's point of view. Defaults to `OUTGOING` when omitted; send `INCOMING` for an NF-e of entry. enum: - INCOMING - OUTGOING default: OUTGOING example: INCOMING identifier: type: string description: Your identifier for the document. example: NFE-123456 serie: type: string description: NF-e series. example: '1' number: type: string description: NF-e number. example: '123456' total_value: type: - number - string description: Total value of the NF-e. example: '1250.00' operation_nature: type: string description: Nature of the operation (natureza da operação) printed on the NF-e. example: Remessa para armazenagem xml_base64: type: string description: Authorized NF-e XML, base64-encoded. example: PD94bWwgdmVyc2lvbj0iMS4wIj8+... pdf_base64: type: string description: DANFE PDF, base64-encoded. example: JVBERi0xLjQK... ReplenishmentStatus: type: string description: > Lifecycle status of a replenishment. - `WITHOUT_SCHEDULING`: created at a warehouse that books receiving appointments natively, but no appointment has been scheduled yet. - `PENDING`: registered but not yet requested to the warehouse (pre-arrival). - `REQUESTED`: announced to the warehouse and awaiting arrival; the initial status at warehouses without native appointment scheduling, and the status after an appointment is booked. - `IN_TRANSIT`: the shipment is on its way to the warehouse. - `RECEIVED`: the shipment was recorded at the dock; counting has not started. - `PROCESSING`: the warehouse is receiving and counting the units (stock has arrived). - `IN_PUTAWAY`: received units are being placed in storage locations. - `COMPLETED`: receiving and putaway finished; `completed_at` is set. - `CANCELED`: the replenishment was canceled; it no longer counts for external-reference uniqueness. enum: - WITHOUT_SCHEDULING - PENDING - REQUESTED - IN_TRANSIT - RECEIVED - PROCESSING - IN_PUTAWAY - COMPLETED - CANCELED example: REQUESTED ReplenishmentProduct: type: object description: One announced line of a replenishment. properties: product_id: type: integer description: Cubbo product id of the line. example: 9001 expected_quantity: type: integer description: Number of units announced for this product. example: 100 unit_value: type: - string - 'null' description: >- Declared unit cost in the store currency, as a decimal string; `null` when not declared. example: '12.5' product: $ref: '#/components/schemas/ReplenishmentLineProduct' ReplenishmentWarehouse: type: object description: Destination warehouse of the replenishment. properties: id: type: integer description: Warehouse id. example: 7 name: type: string description: Warehouse name. example: Mexico City unique_code: type: - string - 'null' description: Warehouse code. example: MX-CDMX-1 address1: type: - string - 'null' description: Street address. example: Av. Ejemplo 123 address2: type: - string - 'null' description: Address complement. example: null zip_code: type: - string - 'null' description: Postal code. example: '01000' city: type: - string - 'null' description: City. example: Ciudad de México state: type: - string - 'null' description: State or province. example: CDMX country: type: - string - 'null' description: Country code (`MX`, `BR`, `CO`, ...). example: MX ReplenishmentCreateLot: type: object description: A lot (batch) expected for a line. required: - lot_code - quantity - external_reference properties: lot_code: type: string description: Lot code as printed on the goods. example: LOT-2026-01 quantity: type: integer description: Units of the line expected in this lot. example: 24 external_reference: type: string description: Your reference for this lot line. example: LOT-REF-1 ReplenishmentLineProduct: type: object description: Catalog product referenced by a replenishment line. properties: id: type: integer description: Cubbo product id. example: 9001 name: type: string description: Product name. example: Red T-shirt M bar_code: type: - string - 'null' description: Barcode (UPC/EAN) of the product. example: '7501234567890' is_scannable: type: boolean description: >- Whether units of this product are identified by scanning at the warehouse. example: true product_codes: type: array description: SKUs registered for the product. items: type: object properties: id: type: integer description: Id of the SKU record. example: 31001 sku: type: string description: SKU. example: SKU-RED-M 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 InternalServerError: description: >- Unexpected error. Retry with backoff; if it persists, send the timestamp to Cubbo support. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: 'unexpected error, timestamp: 1760000000' 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.