> ## 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 store from an existing one > Creates a new store in the same account as an existing store (`source_store_id`) used as a template. The new store inherits the source store's billing configuration and, unless you override them, its store type and warehouse. Your credential must have access to the source store, and the source store must already have a billing configuration. - Send `source_shipping_group_ids` to copy specific shipping groups from the source store instead of receiving the country defaults. Doing so also creates an Open API integration for the new store and returns its credentials once in `open_api_integration`. Without `source_shipping_group_ids` no integration is created, the response has no `open_api_integration` key, and the store-scoped endpoints (`PATCH /store`, fiscal account, digital certificate) cannot be used for it. - `default_shipping_group_id` is required whenever `source_shipping_group_ids` is sent; it must be one of the copied ids and must not be a group with only international shipping methods. It becomes the fallback for orders that arrive without a recognized shipping method. - `webhook_consumer_url` and `webhook_feeds` are only accepted together with `source_shipping_group_ids`. The URL is validated for format only (https, real host, no raw IP) and is not probed. When omitted, no webhook signing secret is issued. - The returned `client_secret` and `webhook_consumer_secret` are shown only in this response. The credential grants access to every store of the same account, so treat it as an account-level secret. - The whole operation is transactional: on any validation failure nothing is created. ## OpenAPI ````yaml /openapi.yaml post /stores 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: /stores: post: tags: - Stores summary: Create a store from an existing one description: > Creates a new store in the same account as an existing store (`source_store_id`) used as a template. The new store inherits the source store's billing configuration and, unless you override them, its store type and warehouse. Your credential must have access to the source store, and the source store must already have a billing configuration. - Send `source_shipping_group_ids` to copy specific shipping groups from the source store instead of receiving the country defaults. Doing so also creates an Open API integration for the new store and returns its credentials once in `open_api_integration`. Without `source_shipping_group_ids` no integration is created, the response has no `open_api_integration` key, and the store-scoped endpoints (`PATCH /store`, fiscal account, digital certificate) cannot be used for it. - `default_shipping_group_id` is required whenever `source_shipping_group_ids` is sent; it must be one of the copied ids and must not be a group with only international shipping methods. It becomes the fallback for orders that arrive without a recognized shipping method. - `webhook_consumer_url` and `webhook_feeds` are only accepted together with `source_shipping_group_ids`. The URL is validated for format only (https, real host, no raw IP) and is not probed. When omitted, no webhook signing secret is issued. - The returned `client_secret` and `webhook_consumer_secret` are shown only in this response. The credential grants access to every store of the same account, so treat it as an account-level secret. - The whole operation is transactional: on any validation failure nothing is created. operationId: createStore requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StoreCreateRequest' example: name: Partner Store SP source_store_id: 1234 created_by_email: integrations@example.com store_type: ALL_SERVICES description: Store provisioned via API source_shipping_group_ids: - 101 - 102 default_shipping_group_id: 101 webhook_consumer_url: https://example.com/cubbo/webhooks webhook_feeds: - order_status - inventory_movement - replenishment_status responses: '201': description: >- Store created. The body is the full store record plus, when an integration was created, its credentials. content: application/json: schema: $ref: '#/components/schemas/StoreCreated' example: id: 4821 name: Partner Store SP description: Store provisioned via API created_at: '2026-09-03T14:02:11.000Z' updated_at: '2026-09-03T14:02:11.000Z' tax_id: null invoice_customization: {} state: null tax_regime: null tax_company_name: null tax_address: null tax_address_number: null tax_address_neighborhood: null tax_city: null tax_zipcode: null tax_state_phone: null tax_state_registration: null store_type: ALL_SERVICES b2b: false d2c: true skip_product_lot_in_returns: null receive_only_complete_returns: null return_inspection_enabled: null requires_stock_only_from_confirmed_replenishments: false has_store_branches: false is_oxxo_store: false enable_replenishment_invoices: null enable_removal_order_invoices: null enable_manual_client_invoice: false enable_b2b_cnpj_client_invoice: false account: id: 900 name: Partner Ltd account_type: COMPANY warehouses: - id: 232 name: CD Sao Paulo unique_code: SP1 open_api_integration: client_id: b6e3a1f0-1234-4c9a-9a11-000000000001 client_secret: webhook_consumer_url: https://example.com/cubbo/webhooks webhook_feeds: - order_status - inventory_movement - replenishment_status webhook_consumer_secret: webhook_consumer_secret_reason: null '401': $ref: '#/components/responses/Unauthorized' '422': description: Validation or business error content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingName: value: error: Parameter name is required sourceStoreNotFound: value: error: source store 1234 not found creatorNotFound: value: error: >- No user with email integrations@example.com found in the source store's account warehouseNotFound: value: error: warehouse 55 not found warehouseNotAssigned: value: error: warehouse 55 is not assigned to the source store noWarehouse: value: error: no warehouse available for the new store invalidStoreType: value: error: >- Invalid store_type. Valid options are: ALL_SERVICES, PICK_AND_SHIP, DEMO_ALL_SERVICES defaultGroupRequiresCopy: value: error: >- default_shipping_group_id requires source_shipping_group_ids webhookUrlRequiresCopy: value: error: webhook_consumer_url requires source_shipping_group_ids webhookFeedsRequireCopy: value: error: webhook_feeds requires source_shipping_group_ids webhookFeedsRequireUrl: value: error: webhook_feeds requires webhook_consumer_url defaultGroupRequired: value: error: >- default_shipping_group_id is required with source_shipping_group_ids defaultGroupNotInList: value: error: >- default_shipping_group_id must be one of source_shipping_group_ids defaultGroupInternational: value: error: >- default_shipping_group_id cannot be a shipping group with international shipping methods invalidWebhookUrl: value: error: webhook_consumer_url must be https invalidWebhookFeed: value: error: >- Parameter webhook_feeds[1] must be within ["order_status", "inventory_movement", "replenishment_status"] noShippingGroupsFound: value: error: >- No shipping groups found on source store 1234 for the given ids '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: schemas: StoreCreateRequest: type: object required: - name - source_store_id - created_by_email properties: name: type: string description: Name of the new store example: Partner Store SP source_store_id: type: integer description: >- Id of an existing store used as template. The new store is created in the same account. Your credential must have access to it. example: 1234 created_by_email: type: string format: email description: >- Email of an existing user of the source store's account, recorded as the creator. The user is not created by this call. example: integrations@example.com store_type: type: string description: Service model of the new store. Defaults to the source store's type. enum: - ALL_SERVICES - PICK_AND_SHIP - DEMO_ALL_SERVICES example: ALL_SERVICES warehouse_id: type: integer description: >- Warehouse for the new store. Must already be assigned to the source store. Defaults to the source store's first warehouse. example: 232 description: type: - string - 'null' description: Free-text description default: null example: Store provisioned via API source_shipping_group_ids: type: array description: >- Ids of the source store's shipping groups to copy. Replaces the country defaults and creates the new store's Open API integration. items: type: integer example: - 101 - 102 default_shipping_group_id: type: integer description: >- Which of `source_shipping_group_ids` becomes the default group. Required with `source_shipping_group_ids`; must not be an international-only group. example: 101 webhook_consumer_url: type: string format: uri description: >- HTTPS URL that will receive the new store's webhooks. Only with `source_shipping_group_ids`. Must use https and a domain name (no raw IP). example: https://example.com/cubbo/webhooks webhook_feeds: type: array description: >- Feeds to deliver to `webhook_consumer_url`. Requires `webhook_consumer_url`. Omitted means all three. items: type: string enum: - order_status - inventory_movement - replenishment_status example: - order_status StoreCreated: description: > Response of `POST /stores`: the full store record (the fields of `Store` plus the store's configuration flags, its `account` and its `warehouses`) and, only when an Open API integration was created, the `open_api_integration` credentials. allOf: - $ref: '#/components/schemas/Store' - type: object properties: b2b: type: boolean description: Whether the store operates business-to-business example: false d2c: type: boolean description: Whether the store operates direct-to-consumer example: true skip_product_lot_in_returns: type: - boolean - 'null' description: Store configuration flag example: null receive_only_complete_returns: type: - boolean - 'null' description: Store configuration flag example: null return_inspection_enabled: type: - boolean - 'null' description: Store configuration flag example: null requires_stock_only_from_confirmed_replenishments: type: boolean description: Store configuration flag example: false has_store_branches: type: boolean description: Store configuration flag example: false is_oxxo_store: type: boolean description: Store configuration flag example: false enable_replenishment_invoices: type: - boolean - 'null' description: Store configuration flag example: null enable_removal_order_invoices: type: - boolean - 'null' description: Store configuration flag example: null enable_manual_client_invoice: type: boolean description: Store configuration flag example: false enable_b2b_cnpj_client_invoice: type: boolean description: Store configuration flag example: false account: type: object description: >- The account the store belongs to (id, name, account type, and the account's stores) additionalProperties: true example: id: 900 name: Partner Ltd account_type: COMPANY warehouses: type: array description: Warehouses assigned to the new store items: type: object additionalProperties: true example: - id: 232 name: CD Sao Paulo unique_code: SP1 open_api_integration: $ref: '#/components/schemas/OpenApiIntegrationCredentials' 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 Store: type: object description: >- A store's identity and fiscal fields, as returned by the store-scoped endpoints properties: id: type: integer description: Store id example: 4821 name: type: string description: Store name example: Partner Store SP description: type: - string - 'null' description: Free-text description example: Store provisioned via API created_at: type: string format: date-time description: Creation time example: '2026-09-03T14:02:11.000Z' updated_at: type: string format: date-time description: Last update time example: '2026-09-03T14:05:47.000Z' tax_id: type: - string - 'null' description: Store tax id (CNPJ in Brazil, digits only; RFC in Mexico) example: '00000000000191' invoice_customization: type: - object - 'null' description: Advanced NF-e customization keyed by invoice purpose (Brazil) additionalProperties: type: object example: {} state: type: - string - 'null' description: State of the store's fiscal address (two-letter UF code in Brazil) example: SP tax_regime: type: - string - 'null' description: Brazilian tax regime enum: - SIMPLES_NACIONAL - LUCRO_REAL - LUCRO_PRESUMIDO - null example: SIMPLES_NACIONAL tax_company_name: type: - string - 'null' description: Legal company name example: Partner Store SP LTDA tax_address: type: - string - 'null' description: Fiscal address street example: Av. Paulista tax_address_number: type: - string - 'null' description: Fiscal address number example: '1000' tax_address_neighborhood: type: - string - 'null' description: Fiscal address neighborhood example: Bela Vista tax_city: type: - string - 'null' description: Fiscal address city example: Sao Paulo tax_zipcode: type: - string - 'null' description: Fiscal address postal code example: 01310-100 tax_state_phone: type: - string - 'null' description: Phone registered with the state registration example: +55 11 0000-0000 tax_state_registration: type: - string - 'null' description: State registration number (Inscricao Estadual) example: '123456789' store_type: type: string description: Service model of the store enum: - ALL_SERVICES - PICK_AND_SHIP - DEMO_ALL_SERVICES example: ALL_SERVICES OpenApiIntegrationCredentials: type: object description: >- Credentials of the new store's Open API integration. Present only when `source_shipping_group_ids` was sent. Secrets are shown once. required: - client_id - client_secret - webhook_consumer_url - webhook_feeds - webhook_consumer_secret - webhook_consumer_secret_reason properties: client_id: type: string description: Credential id to use with `POST /auth/token` to act as the new store example: b6e3a1f0-1234-4c9a-9a11-000000000001 client_secret: type: string description: >- Credential secret, returned only in this response. Grants access to every store of the account. example: webhook_consumer_url: type: - string - 'null' description: >- URL that will receive the store's webhooks, or null when none was sent example: https://example.com/cubbo/webhooks webhook_feeds: type: array description: >- Feeds that will be delivered to `webhook_consumer_url`; empty when no URL was sent items: type: string enum: - order_status - inventory_movement - replenishment_status example: - order_status - inventory_movement - replenishment_status webhook_consumer_secret: type: - string - 'null' description: >- Secret used to sign the webhooks, returned only in this response. Null whenever `webhook_consumer_secret_reason` is set. example: webhook_consumer_secret_reason: type: - string - 'null' description: > Why no secret was returned. `no_webhook_url`: no `webhook_consumer_url` was sent. `reused_from_source_store`: the new store signs with the same secret the source store already uses for this URL. `managed_by_warehouse`: webhook signing for this store is managed by Cubbo; contact your Cubbo representative. Null when a secret is returned. enum: - no_webhook_url - reused_from_source_store - managed_by_warehouse - null example: null 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.