Ankorstore Fulfillment API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Ankorstore Public Fulfillment API
  description: 'The Ankorstore API enables brands and their partners to programmatically manage their presence on the

    Ankorstore wholesale marketplace. Through the API you can manage your product catalog and stock, process

    orders, handle shipping and fulfillment, and receive real-time event notifications via webhooks.


    ### Quick Links


    - **[Getting Started](#section/Getting-Started)** — Register an application, authenticate, and make your first API call

    - **[Available APIs](#section/Available-APIs)** — Overview of all API capabilities

    - **[Authentication](#section/Authentication)** — OAuth2 setup and rate limits

    - **[How to work with API](#section/How-to-work-with-API)** — JSON:API conventions, pagination, filters, and includes

    - **[Testing API](#section/Testing-API)** — Sandbox environment and test data

    - **[Webhook Subscription](#section/Webhook-Subscription)** — Real-time event notifications


    ### Support


    For API support, contact us at [api@ankorstore.com](mailto:api@ankorstore.com).

    '
  contact:
    name: Ankorstore Support
    email: api@ankorstore.com
    url: https://www.ankorstore.com
  license:
    name: CC0 1.0 Universal
    url: https://creativecommons.org/publicdomain/zero/1.0/
  x-prefix: Ankorstore
  x-logo:
    url: https://cdn.ankorstore.com/images/logo/logo-black.svg
    altText: Ankorstore
    href: /
servers:
- url: https://www.public.ankorstore-sandbox.com
  description: Staging Environment
- url: https://www.ankorstore.com
  description: Production Environment
security:
- ProductionOAuth2ClientCredentials: []
tags:
- name: Fulfillment
  description: "ℹ️ Here you can find the information and endpoint specification related to fulfillment of the orders.\n\n## \U0001F4A1 About Fulfillment\n\n_Fulfillment_ is the process of preparing and shipping orders to customers via Ankorstore Fulfillment Centers.\nBrands that use fulfillment send their inventory to a warehouse in advance, and when orders come in, the warehouse\npicks, packs, and ships on the brand's behalf.\n\n### What does \"fulfillable\" mean?\n\nThe concept of a \"fulfillable\" is _that which is required to prepare and ship a product (variant)_.\nWhile a Fulfillment Centre deals exclusively with items, which represents a single item that an employee can pick up and prepare for shipping.\nA fulfillable is simply a set of one or more items, that together represent a product as ordered.\n\nUse the [List Fulfillables](#tag/Fulfillment/operation/fulfillment-list-fulfillable) endpoint to check stock\navailability for specific product variants before creating orders. For more detailed stock information —\nincluding quantities by location, status, and lot — use the\n[Stock State endpoint](/api/astral/v1/stock/state) from the Ankorstore Stock Tracking and Logistics API (ASTRAL).\n\n### Fulfillments\n\nWhen a _Master Order_ has fulfillment requested, one or more _Fulfillments_ are created. Multiple fulfillments\ncan be associated with a single master order (many-to-one). You can retrieve their details and track progress\nthrough the following statuses:\n\n| Status | Description |\n| --- | --- |\n| `requested` | Fulfillment has been requested for the order |\n| `created` | Fulfillment has been created in the warehouse system |\n| `scheduled` | Fulfillment is scheduled for picking |\n| `released` | Fulfillment has been released for picking |\n| `shipped` | Fulfillment has been shipped from the warehouse |\n| `cancelled` | Fulfillment has been cancelled |\n| `cancellation_requested` | A cancellation has been requested but not yet processed |\n\nPass `?include=statusUpdates` when retrieving a fulfillment to see the full history of status transitions.\n\n### Lots\n\nIf your products are lot-tracked or expiry-tracked, the [List Lots](#tag/Fulfillment/operation/fulfillment-list-lots)\nendpoint shows the current lot inventory in the warehouse, including lot numbers, available quantities, and\nexpiry/sell-by dates. You can filter and sort by available quantity, sell-by date range, and product name.\n\n### Fulfillment Costs\n\nUse the [Get Fulfillment Costs](#tag/Fulfillment/operation/fulfillment-costs-get-specifications) endpoint to estimate\nfulfillment costs before committing to an order. Provide the destination country, parcel dimensions, and picking\nquantity to receive a cost breakdown by category (shipping, pick fees by quantity tier).\n\n> ⚠️ The cost estimation does **not** include packing consumables. The actual invoiced amount may differ.\n\n## Replenishments\n\nReplenishments are required to send inventory to the warehouse. They follow a specific workflow:\n\n### Replenishment Workflow\n\n<pre class=\"mermaid\">\nstateDiagram-v2\n    direction LR\n    [*] --> created\n    created --> confirmed : Brand confirms\n    confirmed --> sent : Sent to warehouse\n    sent --> delivered : Arrives at warehouse\n    delivered --> received : Items put into stock\n    received --> [*]\n</pre>\n\n* **Created**: When a replenishment is initially created, it will be at status `created` and is considered a draft. In this state, it can be edited via PATCH requests or deleted.\n* **Confirmed**: Once editing is complete, the status should be updated to `confirmed` as part of a PATCH request. At this point, the replenishment information will be sent to the warehouse (asynchronously).\n* **Sent**: Once the replenishment information is sent to the warehouse, the status changes to `sent`. The replenishment will remain in this status while waiting for delivery.\n* **Delivered**: When the replenishment physically arrives at the warehouse, its status will be automatically updated to `delivered`.\n* **Received**: Once the items are put into stock at the warehouse, the status will be updated to `received`. At this stage, receipts are added with the received stock quantities and lots.\n\n### Creating a Replenishment\n\nEach replenishment requires a carrier name, shipment type, and a list of items with their fulfillment item IDs\nand quantities:\n\n```json5\n// POST /api/v1/fulfillment/replenishments\n{\n  \"fulfillmentBrandId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"warehouseId\": \"98765432-abcd-ef01-2345-678901234567\",\n  \"shippingCarrierName\": \"DHL\",\n  \"shipmentType\": \"PARCEL\",            // \"LTL\", \"FTL\", or \"PARCEL\"\n  \"items\": [\n    {\n      \"fulfillmentItemId\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n      \"quantity\": 100\n    }\n  ]\n}\n```\n\nAfter creating a replenishment, update its status to `confirmed` via PATCH when you are ready to notify the warehouse.\n\n### How Fulfillment Connects to Orders\n\nThe diagram below shows how fulfillment fits into the order lifecycle:\n\n<pre class=\"mermaid\">\ngraph LR\n    A[Master Order] --> D[Fulfillment 1]\n    A --> E[Fulfillment 2]\n    F[Replenishment] --> G[Warehouse Stock]\n    G --> D\n    G --> E\n</pre>\n\n1. Brands send inventory to the warehouse via _Replenishments_\n2. When fulfillment is requested for a _Master Order_, one or more _Fulfillments_ are created\n3. The warehouse picks items from stock and ships each fulfillment\n4. Use the fulfillment endpoints to track both your inventory and fulfillment status\n"
paths:
  /api/v1/product-variants/{productVariant}/declare-fulfillment-item:
    post:
      summary: Declare product variant as fulfillment item
      operationId: product-variants-declare-fulfillment-item
      tags:
      - Fulfillment
      parameters:
      - name: Accept
        in: header
        description: application/vnd.api+json
        schema:
          type: string
          default: application/vnd.api+json
      - name: productVariant
        in: path
        required: true
        schema:
          type: string
          description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)'
          format: uuid
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    barcode:
                      type: string
                      pattern: ^\d{13,14}$
                    unitsPerBatch:
                      type: integer
                    unitCostMargin:
                      description: Margin (as a percentage) between the cost price and wholesale price. Used for insurance purposes
                      type: number
                      format: float
                      minimum: 0
                      maximum: 100
                    classificationCode:
                      type:
                      - string
                      - 'null'
                    expiryTracked:
                      type: boolean
                    shelfLife:
                      type:
                      - integer
                      - 'null'
                    lotTracked:
                      type: boolean
                    isFragile:
                      type: boolean
                    isOrganic:
                      type: boolean
                    needRepack:
                      type: boolean
                    needRelabel:
                      type: boolean
                    alcoholCode:
                      description: Code for alcohol classification, as used in the warehouse
                      type: integer
                      minimum: 1
                      maximum: 11
                    alcoholPercentage:
                      description: Percentage of alcohol in the item
                      type: number
                      format: float
                      minimum: 0
                      maximum: 100
                    volumeOfLiquidPerPack:
                      description: Volume of liquid per pack in liter
                      type: number
                      format: float
                      minimum: 0
                      maximum: 100
                    icpeCode:
                      description: Installation Classified for the Protection of the Environment, as used in the warehouse
                      type: integer
                      minimum: 1000
                      maximum: 4999
                  required:
                  - barcode
                  - unitCost
      responses:
        '200':
          description: Fulfillment item already exists for this product variant
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties:
                      version:
                        type: string
                      meta:
                        description: Non-standard meta-information that can not be represented as an attribute or relationship.
                        type: object
                        additionalProperties: true
                    additionalProperties: false
        '201':
          description: Fulfillment item successfully created
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties:
                      version:
                        type: string
                      meta:
                        description: Non-standard meta-information that can not be represented as an attribute or relationship.
                        type: object
                        additionalProperties: true
                    additionalProperties: false
        '401':
          description: Unauthorized
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  errors:
                    type: array
                    uniqueItems: true
                    items:
                      type: object
                      properties:
                        code:
                          description: An application-specific error code, expressed as a string value.
                          type: string
                        detail:
                          description: A human-readable explanation specific to this occurrence of the problem.
                          type: string
                        status:
                          description: The HTTP status code applicable to this problem, expressed as a string value.
                          type: string
                        title:
                          description: The HTTP status code description applicable to this problem
                          type: string
                        source:
                          type: object
                          description: Optional object pointing towards the problematic field
                          properties:
                            pointer:
                              type: string
                              description: The field key
                        meta:
                          description: Non-standard meta-information that can not be represented as an attribute or relationship.
                          type: object
                          additionalProperties: true
                      additionalProperties: false
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties:
                      version:
                        type: string
                      meta:
                        description: Non-standard meta-information that can not be represented as an attribute or relationship.
                        type: object
                        additionalProperties: true
                    additionalProperties: false
                required:
                - errors
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Unauthorized
                  status: '401'
        '403':
          description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)'
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  errors:
                    type: array
                    uniqueItems: true
                    items:
                      type: object
                      properties:
                        code:
                          description: An application-specific error code, expressed as a string value.
                          type: string
                        detail:
                          description: A human-readable explanation specific to this occurrence of the problem.
                          type: string
                        status:
                          description: The HTTP status code applicable to this problem, expressed as a string value.
                          type: string
                        title:
                          description: The HTTP status code description applicable to this problem
                          type: string
                        source:
                          type: object
                          description: Optional object pointing towards the problematic field
                          properties:
                            pointer:
                              type: string
                              description: The field key
                        meta:
                          description: Non-standard meta-information that can not be represented as an attribute or relationship.
                          type: object
                          additionalProperties: true
                      additionalProperties: false
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties:
                      version:
                        type: string
                      meta:
                        description: Non-standard meta-information that can not be represented as an attribute or relationship.
                        type: object
                        additionalProperties: true
                    additionalProperties: false
                required:
                - errors
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Forbidden
                  status: '403'
        '406':
          description: Not Acceptable
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  errors:
                    type: array
                    uniqueItems: true
                    items:
                      type: object
                      properties:
                        code:
                          description: An application-specific error code, expressed as a string value.
                          type: string
                        detail:
                          description: A human-readable explanation specific to this occurrence of the problem.
                          type: string
                        status:
                          description: The HTTP status code applicable to this problem, expressed as a string value.
                          type: string
                        title:
                          description: The HTTP status code description applicable to this problem
                          type: string
                        source:
                          type: object
                          description: Optional object pointing towards the problematic field
                          properties:
                            pointer:
                              type: string
                              description: The field key
                        meta:
                          description: Non-standard meta-information that can not be represented as an attribute or relationship.
                          type: object
                          additionalProperties: true
                      additionalProperties: false
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties:
                      version:
                        type: string
                      meta:
                        description: Non-standard meta-information that can not be represented as an attribute or relationship.
                        type: object
                        additionalProperties: true
                    additionalProperties: false
                required:
                - errors
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Not Acceptable
                  status: '406'
        '415':
          description: Unsupported Media Type
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  errors:
                    type: array
                    uniqueItems: true
                    items:
                      type: object
                      properties:
                        code:
                          description: An application-specific error code, expressed as a string value.
                          type: string
                        detail:
                          description: A human-readable explanation specific to this occurrence of the problem.
                          type: string
                        status:
                          description: The HTTP status code applicable to this problem, expressed as a string value.
                          type: string
                        title:
                          description: The HTTP status code description applicable to this problem
                          type: string
                        source:
                          type: object
                          description: Optional object pointing towards the problematic field
                          properties:
                            pointer:
                              type: string
                              description: The field key
                        meta:
                          description: Non-standard meta-information that can not be represented as an attribute or relationship.
                          type: object
                          additionalProperties: true
                      additionalProperties: false
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties:
                      version:
                        type: string
                      meta:
                        description: Non-standard meta-information that can not be represented as an attribute or relationship.
                        type: object
                        additionalProperties: true
                    additionalProperties: false
                required:
                - errors
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Unsupported Media Type
                  status: '415'
        '422':
          description: 'Unprocessable Entity : Data provided are invalid'
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  errors:
                    type: array
                    uniqueItems: true
                    items:
                      type: object
                      properties:
                        code:
                          description: An application-specific error code, expressed as a string value.
                          type: string
                        detail:
                          description: A human-readable explanation specific to this occurrence of the problem.
                          type: string
                        status:
                          description: The HTTP status code applicable to this problem, expressed as a string value.
                          type: string
                        title:
                          description: The HTTP status code description applicable to this problem
                          type: string
                        source:
                          type: object
                          description: Optional object pointing towards the problematic field
                          properties:
                            pointer:
                              type: string
                              description: The field key
                        meta:
                          description: Non-standard meta-information that can not be represented as an attribute or relationship.
                          type: object
                          additionalProperties: true
                      additionalProperties: false
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties:
                      version:
                        type: string
                      meta:
                        description: Non-standard meta-information that can not be represented as an attribute or relationship.
                        type: object
                        additionalProperties: true
                    additionalProperties: false
                required:
                - errors
              example:
                jsonapi:
                  version: string
                errors:
                - detail: The field is required.
                  source:
                    pointer: data.attributes.field
                  status: '422'
                  title: Unprocessable Content
        '500':
          description: '[Server Error](https://jsonapi.org/format/#errors)'
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  errors:
                    type: array
                    uniqueItems: true
                    items:
                      type: object
                      properties:
                        code:
                          description: An application-specific error code, expressed as a string value.
                          type: string
                        detail:
                          description: A human-readable explanation specific to this occurrence of the problem.
                          type: string
                        status:
                          description: The HTTP status code applicable to this problem, expressed as a string value.
                          type: string
                        title:
                          description: The HTTP status code description applicable to this problem
                          type: string
                        source:
                          type: object
                          description: Optional object pointing towards the problematic field
                          properties:
                            pointer:
                              type: string
                              description: The field key
                        meta:
                          description: Non-standard meta-information that can not be represented as an attribute or relationship.
                          type: object
                          additionalProperties: true
                      additionalProperties: false
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties:
                      version:
                        type: string
                      meta:
                        description: Non-standard meta-information that can not be represented as an attribute or relationship.
                        type: object
                        additionalProperties: true
                    additionalProperties: false
                required:
                - errors
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Server Error
                  status: '500'
  /api/v1/fulfillment/bundles:
    get:
      summary: List Fulfillment Bundles
      operationId: fulfillment-list-bundles
      description: Returns a list of fulfillable bundles
      tags:
      - Fulfillment
      parameters:
      - schema:
          type: string
        in: header
        name: Accept
        description: application/vnd.api+json
      - in: query
        name: page[limit]
        schema:
          type: integer
      - in: query
        name: page[offset]
        schema:
          type: integer
      responses:
        '200':
          description: Set of fulfillment bundles
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          default: fulfillment-bundle
                        id:
                          type: string
                          description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)'
                          format: uuid
                        attributes:
                          type: object
                          properties:
                            productVariantId:
                              type: string
                              format: uuid
                            items:
                              type: array
                              items:
                                type: object
                                properties:
                                  fulfillmentItemId:
                                    type: string
                                    format: uuid
                                  quantity:
                                    type: integer
                                    description: The number of items in the bundle
                      required:
                      - type
                      - id
                      - attributes
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties:
                      version:
                        type: string
                      meta:
                        description: Non-standard meta-information that can not be represented as an attribute or relationship.
                        type: object
                        additionalProperties: true
                    additionalProperties: false
                required:
                - data
                - jsonapi
        '401':
          description: Unauthorized
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  errors:
                    type: array
                    uniqueItems: true
                    items:
                      type: object
                      properties:
                        code:
                          description: An application-specific error code, expressed as a string value.
                          type: string
                        detail:
                          description: A human-readable explanation specific to this occurrence of the problem.
                          type: string
                        status:
                          description: The HTTP status code applicable to this problem, expressed as a string value.
                          type: string
                        title:
                          description: The HTTP status code description applicable to this problem
                          type: string
                        source:
                          type: object
                          description: Optional object pointing towards the problematic field
                          properties:
                            pointer:
                              type: string
                              description: The field key
                        meta:
                          description: Non-standard meta-information that can not be represented as an attribute or relationship.
                          type: object
                          additionalProperties: true
                      additionalProperties: false
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties:
                      version:
                        type: string
                      meta:
                        description: Non-standard meta-information that can not be represented as an attribute or relationship.
                        type: object
                        additionalProperties: true
                    additionalProperties: false
                required:
              

# --- truncated at 32 KB (413 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ankorstore/refs/heads/main/openapi/ankorstore-fulfillment-api-openapi.yml