Ankorstore Shipping API

openapi: 3.1.0
info:
  version: 1.2.2-oas3.1
  title: Ankorstore Stock Tracking and Logistics Applications Shipping API
  summary: API specification for the Ankorstore Stock Tracking and Logistics system
  description: Ankorstore Stock Tracking and Logistics (ASTRAL) API specification
  contact:
    name: Ankorstore
    url: https://www.ankorstore.com
    email: api@ankorstore.com
  license:
    url: https://creativecommons.org/publicdomain/zero/1.0/
    name: CC0 1.0 Universal
servers:
- url: http://www.ankorlocal.com:8000
  description: Local Development Server
- url: https://www.preprod.ankorstore.com
  description: Staging Environment
- url: https://www.ankorstore.com
  description: Prod Environment
tags:
- name: Shipping
  description: "ℹ️ Here your can find endpoints related to different types of shipping, available on the platform.\n\n<div class=\"warning\">\n\nPlease note, that shipping information described here is only available for _Internal Orders_.\nFor more details check the [Orders](#tag/Ordering/General-conceptions) section.\n\n</div>\n\n## \U0001F4A1 How to ship an Internal Order?\n\nFor shipping an internal order, Ankorstore provides two methods:\n- `Ankorstore Label` method : For this method, the shipping will be handled by Ankorstore carrier partners. The cost of shipping will be charged to the brand.\n- `Brand Label` method : For this method, the shipping will be handled by the brand itself and Ankorstore will provide a refund.\n\nTo retrieve the shipping quotes, the brand must call the following endpoint:\n- Get quote list : `/v1/orders/:orderId/shipping-quotes`\n\nIn the list of quotes, the `Ankorstore Label` method can be found by the carrier name `ankorstore` :\n```json\n{\n    \"data\": [\n        {\n            \"quoteUuid\": \"1efcd179-5753-6ee0-91a4-72a6c4e49e6a\",\n            \"carrierCode\": \"ankorstore\",\n            \"serviceCode\": \"\",\n            \"serviceCommercialName\": \"\",\n            \"collectionMethod\": [],\n            \"shippingCost\": {\n                // Amount refunded to the brand if the quote is selected\n                \"amount\": 1006,\n                \"currency\": \"EUR\"\n            },\n            \"timeInTransit\": null\n        }\n    ]\n}\n```\nOther methods have a different `carrierCode`:\n```json\n{\n    \"data\": [\n        {\n            \"quoteUuid\": \"1edd47df-b91a-68b0-b517-52e73cd28d4f\",\n            \"carrierCode\": \"ups\",\n            \"serviceCode\": \"11\",\n            \"serviceCommercialName\": \"UPS Standard\",\n            \"collectionMethod\": [\n                \"pickup\",\n                \"drop-off\"\n            ],\n            \"shippingCost\": {\n                // Amount subtracted from total amount if the quote is selected\n                \"amount\": 807,\n                \"currency\": \"EUR\"\n            },\n            \"timeInTransit\": {\n                \"estimatedDeliveryDate\": \"2025-01-10\",\n                \"pickupDate\": \"2025-01-08\",\n                \"businessDaysInTransit\": 2\n            }\n        }\n    ]\n}\n```\n\nOnce the quote is generated, the brand must confirm the selected one by calling :\n- Confirm shipping : `/v1/shipping-quotes/:quoteId/confirm`\n\n<div class=\"info\">\n\nTo find out more about Ankorstore's shipping options, please [visit our FAQs.](https://ankorstoresas.my.site.com/faq/s/article/what-shipping-options-are-available-with-ankorstore?language=en_US)\n\n</div>\n\nThe brand can list many quotes before they decide to **confirm** the quote. An example flow:\n\n<pre class=\"mermaid\">\nflowchart LR\n    A[Start] --> B[Get shipping quote list: <br> orders/:orderId/shipping-quotes]\n    B --> B.1{ankorstore carrier quote selected ?}\n    B.1 -- NO --> B.YES[The brand will get the quote amount as a refund for the shipping]\n    B.1 -- YES --> B.NO[The brand will be charged for the shipping by the quote amount]\n    B.YES --> D[I Confirm the quote: <br> shipping-quotes/:quoteId/confirm]\n    B.NO --> D\n</pre>\n\n<div class=\"warning\">\n\n#### Parcels\n\nOn either shipping method, if the brand has previously generated a quote and is now generating a new one\nthe full list of parcels must be provided. The quote endpoint **cannot** be called with an empty parcel list\nto re-use the old parcel data.\n\n</div>\n\n<div class=\"danger\">\n\n#### Confirming a quote\n\nTo confirm a quote, the ID must be provided when calling the `/v1/shipping-quotes/:quoteId/confirm` endpoint.\n\n</div>\n\nAll information regarding shipping and tracking is stored within the `shippingOverview` object. This includes the `latestQuote` generated and the `shippingCostsOverview`.\n\n## \U0001F4A1 Shipping Costs\n\nIn the endpoint for listing quotes `v1/orders/:orderId/shipping-quotes`, the shipping cost of the selected\nquote will be the **fee** subtracted from total amount for carriers (`ups`, `dhl_express`, etc) and a **refund** amount\nfor `ankorstore` carrier (amount refunded to the brand):\n```json\n{\n    \"data\": [\n        {\n            \"quoteUuid\": \"1edd47df-b91a-68b0-b517-52e73cd28d4f\",\n            \"carrierCode\": \"ups\",\n            \"serviceCode\": \"11\",\n            \"serviceCommercialName\": \"UPS Standard\",\n            \"collectionMethod\": [\n                \"pickup\",\n                \"drop-off\"\n            ],\n            \"shippingCost\": {\n                // Amount subtracted from total amount if the quote is selected\n                \"amount\": 807,\n                \"currency\": \"EUR\"\n            }\n        },\n        {\n            \"quoteUuid\": \"1efcd179-5753-6ee0-91a4-72a6c4e49e6a\",\n            \"carrierCode\": \"ankorstore\",\n            \"serviceCode\": \"\",\n            \"serviceCommercialName\": \"\",\n            \"collectionMethod\": [],\n            \"shippingCost\": {\n                // Amount refunded to the brand if the quote is selected\n                \"amount\": 1006,\n                \"currency\": \"EUR\"\n            }\n        }\n    ]\n}\n```\n\n<div class=\"info\">\n\n#### Want more information about shipping contribution?\n\nTo find out more about Ankorstore's contribution to your shipping costs, please [visit our FAQs.](https://knowledgecommunity.force.com/faq/s/article/shippingpolicy?language=en_US)\n\n</div>\n\n### Shipping with Brand Label\n\nThe quote action will return an amount that will be refunded back to the brand based on the shipping grid refund matrix.\n\nThe confirm action is synchronous, meaning when the action is called the order resource will have its status\nchanged to `shipped` upon returning a response. It is up to brand to provide tracking details for the retailer when calling this action.\n\n<pre class=\"mermaid\">\nsequenceDiagram\n  participant O as Order\n  participant SWC as Ship : orders/:orderId/shipping-quotes\n  participant SC as Confirm : shipping-quotes/:quoteId/confirm\n  participant SH as Shipped\n\n  O->>SWC: List quotes\n  SWC-->>O: Quote OK\n  O->>SC: Confirm 'ankorstore' carrier quote\n  SC->>SH: Status\n  SC-->>O: OK\n</pre>\n\n<div class=\"info\">\n\nIn the `orders/:orderId/shipping-quotes` endpoint response, the quote uuid generated is the following:\n\n```json\n {\n    \"quoteUuid\": \"1efcd179-56c1-6432-98e7-72a6c4e49e6a\",\n    \"carrierCode\": \"ankorstore\",\n     ...\n   }\n }\n```\n\n</div>\n\n### Shipping with Ankorstore Label (carrier name like ups, dhl_express, etc)\n\nWhen calling the `confirm` action for the order's Ankorstore shipping quote, the returned order resource's status\nwill still be `brand_confirmed`. A job in the background will generate the shipping labels for the order.\nIt is this background processing that moves the status to `shipping_labels_generated`.\n\n<div class=\"info\">\n\n#### How will I know when the labels have been generated?\n\nRight now, the order must be polled periodically. Checking every minute would be suitable to detect the status change\nand then pull the label PDF data within the shippingOverview of an order resource.\n\n</div>\n\n<pre class=\"mermaid\">\nsequenceDiagram\n  participant O as Order\n  participant SWA as Ship with Ankorstore Label : <br> orders/:orderId/shipping-quotes\n  participant SC as Confirm shipping : <br> shipping-quotes/:quoteId/confirm\n  participant BG as Async Processing\n  participant C as Carrier\n  participant SH as Shipped\n\n  O->>SWA: Get shipping quote list\n  SWA-->>O: I accept one quote\n  O->>SC: I confirm the quote\n  SC-->>O: OK status=brand_confirmed\n  SC-->>BG: Dispatch generate labels job\n  Note over SC,BG: Async worker job\n  BG-->>O: Labels generated, status=shipping_labels_generated\n  Note over BG,O: (Async worker)\n  C-->>SH: Parcels scanned, status=shipped\n  Note over C,SH: (External service)\n</pre>\n\nAt step 6 (shipping labels generated) the download URL's for each packages label will be available within\nthe shippingOverview of an order resource. These labels are in PDF format and will also be visible in order details page on Ankorstore.\n\nIn the `orders/:orderId/shipping-quotes` endpoint response, the quote uuid generated is the following:\n\n```json\n {\n    \"quoteUuid\": \"1efcd179-56c1-6432-98e7-72a6c4e49e6a\",\n    \"carrierCode\": \"ups\",\n     ...\n   }\n }\n```\n\n### Schedule a Pickup\n\nIf the brand is not taking the parcels to the local drop-off point for the carrier the brand can schedule a pickup\nfor this order. A pickup can only be scheduled on a working day (monday to friday).\nFor full information please refer to the API documentation.\n\n<div class=\"info\">\n\n#### Pickup is not accepted\n\nFor now, Ankorstore does not know in advance which date/time configuration is available,\nif the requested pickup is denied please try a different date or time frame.\n\n</div>\n\n## ⚠️ Deprecation notice\n\n<div class=\"warning\">\n\nSome of the endpoints and documents from this section are deprecated and will be removed in the future.\nYou can temporarily still find them [here](#tag/Deprecated).\n\n</div>\n"
paths:
  /api/v1/master-orders/{orderId}/tracking:
    get:
      summary: List master order shipment tracking
      description: Retrieve shipment information like the parcels and the tracking information
      operationId: get-master-order-shipping-shipment
      tags:
      - Shipping
      parameters:
      - name: Accept
        in: header
        description: application/vnd.api+json
        schema:
          type: string
          default: application/vnd.api+json
      - name: orderId
        in: path
        required: true
        schema:
          type: string
          description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)'
          format: uuid
      - name: include
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: string
          enum:
          - shipmentParcel
          - shipmentQuote
          - shippedItems
      responses:
        '200':
          description: Shipment tracking information
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type:
                    - 'null'
                    - object
                    properties:
                      type:
                        type: string
                        default: shipment-trackings
                      id:
                        type: string
                        description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)'
                        format: uuid
                      attributes:
                        type: object
                        additionalProperties: false
                        required:
                        - carrier
                        - trackingNumber
                        - trackingLink
                        - status
                        properties:
                          carrier:
                            type:
                            - 'null'
                            - string
                          serviceCode:
                            type:
                            - 'null'
                            - string
                          trackingNumber:
                            type: string
                          trackingLink:
                            type:
                            - 'null'
                            - string
                          status:
                            type:
                            - 'null'
                            - string
                      relationships:
                        type: object
                        description: Only presented if asked explicitly in the request
                        properties:
                          shipmentParcel:
                            type: object
                            properties:
                              data:
                                description: An array of objects each containing `type` and `id` members for to-many relationships.
                                type: array
                                items: &id003
                                  description: Resource identification present in Resource Objects and Resource Identifier Objects.
                                  type: object
                                  required: &id001
                                  - id
                                  - type
                                  properties: &id002
                                    id:
                                      type: string
                                      description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)'
                                      format: uuid
                                    type:
                                      type: string
                                      description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)'
                                    meta:
                                      description: Non-standard meta-information that can not be represented as an attribute or relationship.
                                      type: object
                                      additionalProperties: true
                                  additionalProperties: false
                                uniqueItems: true
                          shipmentQuote:
                            type: object
                            properties:
                              data:
                                description: Resource identification present in Resource Objects and Resource Identifier Objects.
                                type: object
                                required: *id001
                                properties: *id002
                                additionalProperties: false
                          shippedItems:
                            type: object
                            description: Only presented if asked explicitly in the request with ?include=shippedItems
                            properties:
                              data:
                                description: An array of objects each containing `type` and `id` members for to-many relationships.
                                type: array
                                items: *id003
                                uniqueItems: true
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties: &id004
                      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
                  included:
                    type: array
                    items:
                      anyOf:
                      - properties:
                          type:
                            type: string
                            default: tracked-packages
                          id:
                            type: string
                            description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)'
                            format: uuid
                          attributes:
                            type: object
                            additionalProperties: false
                            required:
                            - trackingNumber
                            - trackingLink
                            - status
                            properties:
                              height:
                                description: Height of the package (cm)
                                type:
                                - 'null'
                                - integer
                              width:
                                description: Width of the package (cm)
                                type:
                                - 'null'
                                - integer
                              length:
                                description: Length of the package (cm)
                                type:
                                - 'null'
                                - integer
                              weight:
                                description: Weight of the package (g)
                                type:
                                - 'null'
                                - integer
                              trackingNumber:
                                type: string
                                description: Tracking number of the package
                              trackingLink:
                                type: string
                                description: Tracking link of the package
                              status:
                                type: string
                                description: Status of the package
                              serialShippingContainerCode:
                                type:
                                - 'null'
                                - string
                                description: Serial Shipping Container Code (SSCC) for traceability
                              label:
                                type:
                                - 'null'
                                - object
                                description: Label of the package
                                properties:
                                  content:
                                    type: string
                                    description: Content of the label
                                  contentType:
                                    type: string
                                    description: Content type of the label (gif, pdf)
                      - properties:
                          type:
                            type: string
                            default: shipping-shipment-shipped-item
                          id:
                            type: string
                            description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)'
                            format: uuid
                          attributes:
                            type: object
                            additionalProperties: false
                            required:
                            - parcelId
                            - productVariantId
                            - batchQuantity
                            - unitQuantity
                            properties:
                              parcelId:
                                type: string
                                format: uuid
                                description: The UUID of the parcel (tracked package) this item belongs to
                              productVariantId:
                                type: string
                                format: uuid
                                description: The UUID of the product variant
                              batchQuantity:
                                type: integer
                                minimum: 1
                                description: Number of batches (e.g. boxes) shipped
                              unitQuantity:
                                type: integer
                                minimum: 1
                                description: Number of individual units shipped
                              lotNumber:
                                type:
                                - 'null'
                                - string
                                description: Lot or batch number for traceability
                              expiryDate:
                                type:
                                - 'null'
                                - string
                                format: date
                                description: Expiry date of the items (YYYY-MM-DD)
                required:
                - data
                - jsonapi
        '401':
          description: Unauthorized
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: &id005
                  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: *id004
                    additionalProperties: false
                required: &id006
                - errors
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Unauthorized
                  status: '401'
        '404':
          description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)'
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id005
                required: *id006
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Not found
                  status: '404'
        '406':
          description: Not Acceptable
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id005
                required: *id006
              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: *id005
                required: *id006
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Unsupported Media Type
                  status: '415'
    post:
      summary: Create master order shipment tracking
      description: Create shipment information like the parcels and the tracking information
      operationId: post-master-order-shipping-shipment
      tags:
      - Shipping
      parameters:
      - name: Accept
        in: header
        description: application/vnd.api+json
        schema:
          type: string
          default: application/vnd.api+json
      - name: orderId
        in: path
        required: true
        schema:
          type: string
          description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)'
          format: uuid
      - name: include
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: string
          enum:
          - shipmentParcel
          - shipmentQuote
          - shippedItems
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                      - shipping-shipment
                    id:
                      type: string
                      description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)'
                      format: uuid
                    attributes:
                      type: object
                      additionalProperties: false
                      required:
                      - status
                      - carrier
                      properties:
                        carrier:
                          type:
                          - 'null'
                          - string
                          description: The carrier name - set 'other' if the carrier is not known yet
                        trackingNumber:
                          type:
                          - 'null'
                          - string
                        trackingLink:
                          type:
                          - 'null'
                          - string
                          description: Tracking link to the carrier's website - if null and if the carrier is known, the tracking link will be generated by Ankorstore
                        status:
                          type: string
                          enum:
                          - UNKNOWN
                          - PRE_TRANSIT
                          - TRANSIT
                          - DELIVERED
                          - RETURNED
                          - FAILURE
                        fromAddress:
                          description: The address from where the parcels are shipped
                          type: object
                          properties:
                            data:
                              type: object
                              required:
                              - name
                              - street
                              - city
                              - postalCode
                              - countryCode
                              properties:
                                name:
                                  type: string
                                street:
                                  type: string
                                city:
                                  type: string
                                postalCode:
                                  type: string
                                countryCode:
                                  type: string
                                  format: iso3166-1-alpha-2
                    relationships:
                      type: object
                      required:
                      - shipmentParcel
                      properties:
                        shipmentParcel:
                          type: object
                          properties:
                            data:
                              type: array
                              items:
                                type: object
                                required:
                                - type
                                - id
                                properties:
                                  type:
                                    type: string
                                    enum:
                                    - shipping-shipment-parcel
                                  id:
                                    type: string
                                    description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)'
                                    format: uuid
                                  attributes:
                                    type: object
                                    additionalProperties: false
                                    required:
                                    - status
                                    properties:
                                      trackingNumber:
                                        type:
                                        - 'null'
                                        - string
                                      trackingLink:
                                        type:
                                        - 'null'
                                        - string
                                        description: Tracking link to the carrier's website - if null and if the carrier is known, the tracking link will be generated by Ankorstore
                                      status:
                                        type: string
                                        enum:
                                        - UNKNOWN
                                        - PRE_TRANSIT
                                        - TRANSIT
                                        - DELIVERED
                                        - RETURNED
                                        - FAILURE
                                      length:
                                        description: The length of the parcel in cm
                                        type:
                                        - 'null'
                                        - integer
                                      width:
                                        description: The width of the parcel in cm
                                        type:
                                        - 'null'
                                        - integer
                                      height:
                                        description: The height of the parcel in cm
                                        type:
                                        - 'null'
                                        - integer
                                      weight:
                                        description: The weight of the parcel in grams
                                        type:
                                        - 'null'
                                        - integer
                                      sscc:
                               

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