Powered by Redocly

Comestri OMS - Web Integration (4.13.1)

Download OpenAPI specification:Download

This API provides directs integration points with Comestri OMS to connect to websites, warehouse systems and sales ledgers.

For a website connectivity to Salesforce Commerce Cloud or to Adobe Commerce Cloud, a cartridge or extension is available, surfacing this same functionality in the platform's native environment.

Integrations for Product data are routed through the Comestri hub. The product schema passed between the Comestri PIM and Comestri OMS are included in this document for reference.

This document is published at https://comestrioms.redoc.ly, which will be updated from time to time with clarifications, additional examples or further detail. If any material changes are required during final development and testing of the API, a new document will be provided, including an analysis of any changes against this draft.

Find out more about the Comestri OMS

Website Integration

Determine stock availability in nearby stores.

List the stores in which the item(s) are available to collect, within the same country of the customer's location. List of stores returned is order starts from closest, at most 25 stores will be returned by default which suffice for most situation.

For inputting list of line items in the query, there are two ways of constructing the URL query, for example, assume the list of line times are prod01 x2 and prod02 x3, then the request URL could be:

.../store-availability?country_code=au&postcode=2025&channel=tmall&web_sku_ids=prod01&quantities=2&web_sku_ids=prod02&quantities=3

or

.../store-availability?country_code=au&postcode=2025&channel=tmall&web_sku_ids=prod01,prod02&quantities=3,2

Along with country_code, one of the following is required to denote the approximate destination:

  • postcode
  • postal_area
  • latitude with longitude

    • query Parameters
    country_code
    required
    string <ISO 3166-1 alpha-2 codes> <= 2 characters

    The country code of the destination.

    Example: country_code=AU
    postcode
    string <= 4 characters

    The postal code of the destination. This parameter should be used along with country_code.

    This parameter is incompatible with postal_area, longitude and latitude.

    Example: postcode=4000
    postal_area
    string <= 4 characters

    The postal area of the destination. This parameter should be used along with country_code.

    This parameter is only applicable to countries that do not use postal codes.
    It is incompatible with postcode, longitude and latitude.

    Example: postal_area=Central
    latitude
    number

    The latitude coordinate of the approximate destination of the order.
    Must be used together with longitude and country_code.

    This parameter is incompatible with postcode and postal_area.

    Example: latitude=-33.865143
    longitude
    number

    The longitude coordinate of the approximate destination of the order.
    Must be used together with latitude and country_code.

    This parameter is incompatible with postcode and postal_area.

    Example: longitude=151.2099
    transfer_policy
    string (TransferPolicy)

    Future


    For a click-and-collect order, the policy that has been agreed with the customer for items that are not immediately available for collection (whether stock availability is known in advance, or in the event that stock expected in the collection location cannot actually be found).

    "no-transfer" means that a transfer will not be allowed; any items that cannot be found will be automatically cancelled, and an apology will be sent to the customer.

    "single-collection" means that items will be transferred from another location to the collection location, and the customer will be informed when all items are ready to collect.

    "multi-collection" means that items will be transferred from another location, but the customer will be informed as soon as any items are ready for collection, and then again when the transfer arrives at the collection location.

    "shipping" means that any items cannot be located at the collection location will be shipped to the customer address.

    Enum: "no-transfer" "single-collection" "multi-collection" "shipping"
    channel
    string

    Sales channel for order, such as a marketplace. If this field is provided, the fulfilment rule assigned to the sales channel will be chosen to determine the available stores.

    web_sku_ids
    required
    string

    List of The primary identifier of the items in the order.

    Example: web_sku_ids=prod01
    quantities
    required
    number

    List of the quantities for the items in the order corresponding to the list provided in web_sku_ids.

    Example: quantities=3
    max_stores
    integer

    The maximum number of stores to be listed. Default 25 if not specified.

    au_postcode
    string <= 4 characters
    Deprecated

    The approximate destination of the order denoted by a Australia Postal Code.

    This parameter is incompatible with nz_postcode, country_code, longitude, latitude.

    Example: au_postcode=4000
    nz_postcode
    string <= 4 characters
    Deprecated

    The approximate destination of the order denoted by a New Zealand Postal Code.

    This parameter is incompatible with au_postcode, country_code, longitude, latitude.

    Example: nz_postcode=1010

    Responses

    Response samples

    Content type
    application/json
    {
    • "collection_options": [
      ]
    }

    Determine available Delivery Options

    Determine the delivery options that may be offered to the customer for a particular set of items, and the fulfilment cost of each.

    For inputting list of line items in the query, there are two ways of constructing the URL query, for example, assume the list of line times are prod01 x2 and prod02 x3, then the request URL could be:

    .../delivery-options?country_code=au&postcode=2025&collection_store=332&channel=tmall &web_sku_ids=prod01&quantities=2&web_sku_ids=prod02&quantities=3

    or

    .../delivery-options?country_code=au&postcode=2025&collection_store=332&channel=tmall &web_sku_ids=prod01,prod02&quantities=3,2

    Along with country_code, one of the following is required to denote the approximate destination:

  • postcode
  • postal_area
  • latitude with longitude

    • query Parameters
    country_code
    required
    string <ISO 3166-1 alpha-2 codes> <= 2 characters

    The country code of the destination.

    Example: country_code=AU
    postcode
    string <= 4 characters

    The postal code of the destination. This parameter should be used along with country_code.

    This parameter is incompatible with postal_area, longitude and latitude.

    Example: postcode=4000
    postal_area
    string <= 4 characters

    The postal area of the destination. This parameter should be used along with country_code.

    This parameter is only applicable to countries that do not use postal codes.
    It is incompatible with postcode, longitude and latitude.

    Example: postal_area=Central
    latitude
    number

    The latitude coordinate of the approximate destination of the order.
    Must be used together with longitude and country_code.

    This parameter is incompatible with postcode and postal_area.

    Example: latitude=-33.865143
    longitude
    number

    The longitude coordinate of the approximate destination of the order.
    Must be used together with latitude and country_code.

    This parameter is incompatible with postcode and postal_area.

    Example: longitude=151.2099
    collection_store
    string

    The location number (ERP ID) of a specific store to be considered for click-and-collect pricing; as configured in both the OMS and the Sales Channel (or as configured in the Comestri PIM and published to both)

    transfer_policy
    string (TransferPolicy)

    Future


    For a click-and-collect order, the policy that has been agreed with the customer for items that are not immediately available for collection (whether stock availability is known in advance, or in the event that stock expected in the collection location cannot actually be found).

    "no-transfer" means that a transfer will not be allowed; any items that cannot be found will be automatically cancelled, and an apology will be sent to the customer.

    "single-collection" means that items will be transferred from another location to the collection location, and the customer will be informed when all items are ready to collect.

    "multi-collection" means that items will be transferred from another location, but the customer will be informed as soon as any items are ready for collection, and then again when the transfer arrives at the collection location.

    "shipping" means that any items cannot be located at the collection location will be shipped to the customer address.

    Enum: "no-transfer" "single-collection" "multi-collection" "shipping"
    channel
    string

    Sales channel for order, such as a marketplace. If this field is provided, the fulfilment rule assigned to the sales channel will be chosen to determine the available delivery options.

    web_sku_ids
    required
    string

    List of The primary identifier of the items in the order.

    Example: web_sku_ids=prod01
    quantities
    required
    number

    List of the quantities for the items in the order corresponding to the list provided in web_sku_ids.

    Example: quantities=3
    au_postcode
    string <= 4 characters
    Deprecated

    The approximate destination of the order denoted by a Australia Postal Code.

    This parameter is incompatible with nz_postcode, country_code, longitude, latitude.

    Example: au_postcode=4000
    nz_postcode
    string <= 4 characters
    Deprecated

    The approximate destination of the order denoted by a New Zealand Postal Code.

    This parameter is incompatible with au_postcode, country_code, longitude, latitude.

    Example: nz_postcode=1010

    Responses

    Response samples

    Content type
    application/json
    {
    • "shipping_options": [
      ],
    • "currency_of_costs": "AUD"
    }

    Confirm a provisional order with given delivery options

    Before the customer proceeds to pay for an order, the website must use this API to verify that the selected items and delivery options can actually be fulfilled, to protect against oversell. If changes are made during the checkout process, the website may call the API again with updates.

    If the delivery_service is "standard-shipping", "express-shipping" or "hand-delivery", one of the following is required to denote the approximate destination along with country_code:

  • postcode
  • postal_area
  • latitude and longitude

    • path Parameters
    channel
    required
    string

    The sales channel.

    id
    required
    string

    Shopping basket, quote, or provisional order number.

    Example: 123123
    Request Body schema: application/json
    required
    object

    Courier Service options requested by the customer, which will be used by the OMS to select an appropriate courier and service.

    collection_location
    string

    This is required if delivery_service is "collection".

    This is the store where the items will be collected.
    The value can be an ERP ID or a 6-digit OMS Branch ID.

    ERP ID is configured in both the OMS and the Sales Channel, or can be configured in the Comestri PIM and then published to OMS and the Sales Channel.

    OMS Branch ID is the 6-digit unique store ID provided by OMS.

    country_code
    required
    string <ISO 3166-1 alpha-2 codes> <= 2 characters

    The country code of the destination.

    postcode
    string <= 4 characters

    The postal code of the destination. This parameter should be used along with country_code.

    This parameter is incompatible with postal_area, longitude and latitude.

    postal_area
    string <= 4 characters
    Deprecated

    The postal area of the destination. This parameter should be used along with country_code.

    This parameter is only applicable to countries that do not use postal codes.
    It is incompatible with postcode, longitude and latitude.

    latitude
    number

    The latitude of the approximate destination of the order.
    This must be used together with longitude.

    This parameter is incompatible with postcode and postal_area.

    longitude
    number

    The longitude of the approximate destination of the order.
    This must be used together with latitude.

    This parameter is incompatible with postcode and postal_area.

    object

    The sales channel may place controls on the way that the order is fulfilled.

    transfer_policy
    string (TransferPolicy)

    Future


    For a click-and-collect order, the policy that has been agreed with the customer for items that are not immediately available for collection (whether stock availability is known in advance, or in the event that stock expected in the collection location cannot actually be found).

    "no-transfer" means that a transfer will not be allowed; any items that cannot be found will be automatically cancelled, and an apology will be sent to the customer.

    "single-collection" means that items will be transferred from another location to the collection location, and the customer will be informed when all items are ready to collect.

    "multi-collection" means that items will be transferred from another location, but the customer will be informed as soon as any items are ready for collection, and then again when the transfer arrives at the collection location.

    "shipping" means that any items cannot be located at the collection location will be shipped to the customer address.

    Enum: "no-transfer" "single-collection" "multi-collection" "shipping"
    object

    Requests from the customer for specific packaging, or to include a gift message with the order.

    required
    Array of objects (SkuQty)

    The items in the basket.

    object
    Deprecated

    Customers may accumulate or redeem loyalty points associated with an order.

    fulfilment_type
    string
    Deprecated

    Whether the order will be shipped to a customer address, or prepared for customer collection. (If the customer wishes to ship some items, but collect other items, then two separate orders must be sent to the OMS.)

    Enum: "shipping" "collection"
    au_postcode
    string <= 4 characters
    Deprecated

    The approximate destination of the order denoted by a Australia Postal Code.

    This parameter is incompatible with nz_postcode, country_code, longitude, latitude.

    nz_postcode
    string <= 4 characters
    Deprecated

    The approximate destination of the order denoted by a New Zealand Postal Code.

    This parameter is incompatible with au_postcode, country_code, longitude, latitude.

    uk_postcode
    string <= 8 characters
    Deprecated

    The approximate destination of the order denoted by a UK Postal Code.

    This parameter is incompatible with au_postcode, nz_postcode, us_zipcode, hk_district, country_code, longitude, latitude.

    us_zipcode
    string <= 5 characters
    Deprecated

    The approximate destination of the order denoted by a USA Zipcode.

    This parameter is incompatible with au_postcode, nz_postcode, uk_postcode, hk_district, country_code, longitude, latitude.

    hk_district
    string <= 2 characters
    Deprecated

    The approximate destination of the order denoted by a Hong Kong District (English).

    This parameter is incompatible with au_postcode, nz_postcode, uk_postcode, us_zipcode, country_code, longitude, latitude.

    Enum: "Islands" "Wan Chai" "Central and Western" "Southern" "Tsuen Wan" "Tai Po" "North" "Yau Tsim Mong" "Sham Shui Po" "Kowloon City" "Wong Tai Sin" "Sai Kung" "Tuen Mun" "Kwai Tsing" "Eastern" "Yuen Long" "Kwun Tong" "Sha Tin"

    Responses

    Request samples

    Content type
    application/json
    {
    • "shipping_options": {
      },
    • "collection_location": "123231",
    • "country_code": "AU",
    • "postcode": "4000",
    • "postal_area": null,
    • "latitude": -33.865143,
    • "longitude": 151.2099,
    • "fulfilment_controls": {
      },
    • "transfer_policy": "no-transfer",
    • "packaging_options": {
      },
    • "skus": [
      ],
    • "loyalty": {
      },
    • "fulfilment_type": null,
    • "au_postcode": null,
    • "nz_postcode": null,
    • "uk_postcode": null,
    • "us_zipcode": null,
    • "hk_district": null
    }

    Response samples

    Content type
    application/json
    {
    • "unavailable_items": [
      ]
    }

    Order Ingestion

    This API can be used for:

    1. Creating new orders.
    2. Replacing shopping cart orders with actual orders.
      • Note that once a shopping cart order has been replaced, the shopping cart order number will no longer exist.
      • Any change in the information given in /set-delivery API will affect the allocation and invalidate the original soft hold.
    3. Updating unprocessed orders (the order status is provisional), with the following restrictions:
      • replaced_order cannot be updated.
      • SKUs from the original order can be updated with removal or reduced quantity only. No new SKUs can be added.
      • If a client has opted out of using OMS Apps for pick/pack (we call this "WMS Model 2"), orders cannot be updated once they have been sent to a 3PL.
    4. Releasing orders that are on hold for payment review by updating fulfilment_controls.hold_for_payment_review from true to false.

    path Parameters
    channel
    required
    string <= 20 characters

    Sales channel for order, such as a marketplace.

    orderNumber
    required
    string <= 64 characters

    Unique order number generated by eCommerce Platform.

    This order number can be used for creating a new order, replacing a shopping cart order, or updating an existing order.

    Example: 3402340
    Request Body schema: application/json
    replaced_order
    string <= 255 characters

    This indicates which shopping cart order this call will replace. This is required when a shopping cart order needs to be replaced with an actual order.

    required
    object

    Customer Selection of the shipping options presented to them.

    object

    This is required if delivery_service is "standard-shipping", "express-shipping" or "hand-delivery".

    collection_location
    string <= 10 characters

    This is required if delivery_service is "collection".

    This is the store where the items will be collected.
    The value can be an ERP ID or a 6-digit OMS Branch ID.

    ERP ID is configured in both the OMS and the Sales Channel, or can be configured in the Comestri PIM and then published to OMS and the Sales Channel.

    OMS Branch ID is the 6-digit unique store ID provided by OMS.

    latitude
    number [ -90 .. 90 ]

    This can be used together with longitude to determine the hand delivery point according to fulfilment rule, if delivery_service is "hand-delivery".

    longitude
    number [ -180 .. 180 ]

    This can be used together with latitude to determine the hand delivery point according to fulfilment rule, if delivery_service is "hand-delivery".

    object

    The client may place controls on the way that the order is fulfilled based on their operational needs.

    transfer_policy
    string (TransferPolicy)

    Future


    For a click-and-collect order, the policy that has been agreed with the customer for items that are not immediately available for collection (whether stock availability is known in advance, or in the event that stock expected in the collection location cannot actually be found).

    "no-transfer" means that a transfer will not be allowed; any items that cannot be found will be automatically cancelled, and an apology will be sent to the customer.

    "single-collection" means that items will be transferred from another location to the collection location, and the customer will be informed when all items are ready to collect.

    "multi-collection" means that items will be transferred from another location, but the customer will be informed as soon as any items are ready for collection, and then again when the transfer arrives at the collection location.

    "shipping" means that any items cannot be located at the collection location will be shipped to the customer address.

    Enum: "no-transfer" "single-collection" "multi-collection" "shipping"
    object

    Packaging options requested by the customer, which will be used by the OMS for pack instructions and printing gift messages.

    currency
    string <ISO-4217 3-digit alpha>

    This indicates the transaction currency of this order. If this is not provided, the client's default currency will be applied.

    required
    Array of objects (SkuQtyInWeb)

    All line items involved in the order. SKUs can be adjusted from the order by calling this API again to reduce the SKU quantity or to remove a SKU, but no new SKUs can be added to the order.

    order_price
    required
    number decimal places <= 2 < 1000000000

    This is the total price of the order, including all line prices, line discounts, line taxes, order discounts, order taxes, shipping fee, shipping fee discount, shipping fee tax, and rounding adjustment.

    Array of objects (Discounts)

    Order-level discounts. This does not include line_discounts. These are separate discounts applied to the whole order.

    Array of objects (Taxes)

    Order-level taxes. This does not include line_taxes. These are separate taxes applied to the whole order.

    rounding_adjustment
    number decimal places <= 2 < 1000000000

    The amount charged to the customer for rounding purpose.

    A positive value means that this value was applied for rounding up, while a negative value means it was applied for rounding down.

    shipping_base_price_exc_tax
    number decimal places <= 2 < 1000000000

    This is the shipping fee charged on the order, excluding discount and tax.

    Array of objects (Discounts)

    Details of discounts for the shipping fee.

    Array of objects (Taxes)

    Details of shipping taxes for the shipping fee.

    Array of objects (TxTenderOnOrderIngestion)

    List of payments used to settle the order.

    object

    Billing information of the customer.

    object

    Customer's contact information.

    object

    Customers may accumulate or redeem loyalty points associated with an order.

    order_creation_time
    string <time (ISO-8601 yyyy-MM-ddTHH:mm:ssZ)>

    Creation time of the order in UTC from the client. If this is not provided, the time of the initial call for this order number will be used.

    additional_info
    string

    Additional info related to the order that can be later retrieved along with the order.

    Responses

    Request samples

    Content type
    application/json
    {
    • "replaced_order": "1204846",
    • "shipping_options": {
      },
    • "shipping_address": {
      },
    • "collection_location": "",
    • "latitude": null,
    • "longitude": null,
    • "fulfilment_controls": {
      },
    • "transfer_policy": "no-transfer",
    • "packaging_options": {
      },
    • "currency": "AUD",
    • "skus": [
      ],
    • "order_price": 257.54,
    • "order_discounts": [
      ],
    • "order_taxes": [
      ],
    • "rounding_adjustment": 0,
    • "shipping_base_price_exc_tax": 20,
    • "shipping_discounts": [
      ],
    • "shipping_taxes": [
      ],
    • "tenders": [
      ],
    • "billing_info": {
      },
    • "customer_info": {
      },
    • "loyalty": {
      },
    • "order_creation_time": "2018-12-28T15:45:32Z",
    • "additional_info": "Staff ID: K00035"
    }

    Response samples

    Content type
    application/json
    {
    • "error_messages": [
      ]
    }

    WMS Integration

    Get Shipment Request

    If the fulfilment rules in Comestri OMS decide the order (or part of it) should be shipped from DC, then Comestri OMS will create a Shipment request, to be passed to the WMS. The caller should poll the OMS /monitor API to determine when shipments are ready, then use this API to get shipment details. This payload can also be delivered by a webhook.

    path Parameters
    shipmentId
    required
    string

    OMS shipment ID.

    Responses

    Response samples

    Content type
    application/json
    {
    • "order_id": "18003563",
    • "shipment_id": "18003563:S939",
    • "shipment_number": "S939",
    • "skus": [
      ],
    • "fulfilment_type": "shipping",
    • "name": "James Tennersby",
    • "phone": "85293405340",
    • "email": "customer@email.com",
    • "address": {
      },
    • "billing_address": {
      },
    • "location": "2022",
    • "packaging_type": "Gift",
    • "packaging_options": {
      },
    • "additional_info": {
      },
    • "shipping_options": {
      }
    }

    Confirm a shipment.

    When a Third Party Store has picked and packed a shipment partially or fully, the store should then use Shipment Confirm API to acknowledge Comestri OMS with information related to shipping. For a partially picked shipment, the details of the pick-failings are specified.

    There are two ways to use the Shipment Confirm API:

    1. The first one is for confirming a shipment and sending necessary pick fail info. This case allows the use of pick_fail_info.
    2. The second one is for confirming some items and indicating whether there are items pending for further processing in a split dispatch. This case allows the use of picked_skus and further_confirm_pending.
    These two sets of parameters are incompatible with each other. If they are used together, only picked_skus and further_confirm_pending will be processed, while pick_fail_info will be ignored.

    path Parameters
    shipmentId
    required
    string

    OMS shipment ID.

    Request Body schema: application/json
    Array of objects (SkuQtyInWMS)

    Items that are picked and shipped in this dispatch. This must not be empty if further_confirm_pending is true.

    This field is incompatible with pick_fail_info.

    object

    Information about the pick fail action. These details are used in Pick Fail report.

    This field is incompatible with picked_skus and further_confirm_pending. If there are SKU items in picked_skus, this field will be ignored.

    further_confirm_pending
    boolean

    This flag indicates that there are more items pending for further processing. If this flag is true, picked_skus must not be empty.

    This field is incompatible with pick_fail_info.

    courier_name
    string

    The OMS name of the courier. If this field is not specified, the highest priority courier that has the specified delivery_service for that fulfilment branch in OMS configurations will be selected.

    It is recommended to always provide this field.

    courier_service
    string

    The name of the selected shipping service offered by the courier (courier_name). This value is used in Order Report.

    courier_tracking_ref
    string <= 500 characters

    The tracking reference provided by the courier for the shipped parcels.

    Array of objects (Parcel)

    Details of parcel(s) into which the shipment has been packed. The parcel information is used in Order report.

    carriage_cost
    number

    The shipping fee paid by the third party store to the courier.

    Array of objects (RelatedDoc)

    Names and URLs to PDF of any related paperwork to be archived for reference.

    staff_name
    string <= 200 characters

    Name of the store staff who performed the pick action.

    If this is not provided, this will automatically be filled in as the name of the location.

    pack_time
    string <time (ISO-8601 yyyy-MM-ddTHH:mm:ssZ)>

    Time in UTC at which packing was completed. This value is used in the Order Report.

    Responses

    Request samples

    Content type
    application/json
    Example
    Example request with pick fail info
    Example request with pick fail info
    Example request for split dispatch with picked SKUs
    {
    • "pick_fail_info": {
      },
    • "courier_name": "AUSPOST",
    • "courier_service": "eParcel Express",
    • "courier_tracking_ref": "43487234GE8",
    • "parcels": [
      ],
    • "carriage_cost": 20.8,
    • "related_docs": [],
    • "staff_name": "Robb",
    • "pack_time": "2019-04-10T21:30:00Z"
    }

    Response samples

    Content type
    application/json
    Example
    Example of syntax error of fields
    Example of syntax error of fields
    Courier name specified cannot be found.
    The document type name specified cannot be identified.
    The number of arrays does not match with the quantity/The number of serial_numbers does not align in all arrays
    {
    • "fields_with_syntax_errors": [
      ]
    }

    Reject a shipment

    When a Third Party Store is unable to process a shipment, the store should then use Shipment Reject API to acknowledge OMS. For example, this API can be used when all the items in a shipment are unavailable.

    path Parameters
    shipmentId
    required
    string

    OMS shipment ID.

    Request Body schema: application/json

    It is assumed that all the SKU(s) in the shipment are pick failed when this API is used.

    object

    Information about the pick fail action. These details are used in Pick Fail report.

    Responses

    Request samples

    Content type
    application/json
    {
    • "pick_fail_info": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "shipment_id": "123-213-321:S939"
    }

    Confirm inventory Allocation.

    Once allocation of items has been completed by WMS, it should confirm when it has finished adjusting available inventory, so OMS knows the items have been accounted in the next SOH delta.

    path Parameters
    shipmentId
    required
    string

    OMS shipment ID.

    Responses

    Response samples

    Content type
    application/json
    {
    • "shipment_id": "123-213-321:S939"
    }

    Set scannable identifier for a shipment.

    Associate the ID of the WMS picking paperwork with OMS shipment, so that, WMS can share the barcodes that have been used for that shipment and to allow WMS picking paperwork to be scanned by OMS.

    path Parameters
    shipmentId
    required
    string

    OMS shipment ID.

    Request Body schema: application/json
    pick_id
    string

    WMS defined pick ID.

    Responses

    Request samples

    Content type
    application/json
    {
    • "pick_id": "PI45340"
    }

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Accept Return

    This API allows clients to accept returns booked through OMS in WMS.

    Request Body schema: application/json
    order_number
    string

    Order number. Either order_number or rma_number is required.

    rma_number
    string <= 100 characters

    Return material authorization number. Either order_number or rma_number is required.

    time
    string <time (ISO-8601 yyyy-MM-ddTHH:mm:ssZ)>

    Time in UTC when the return is accepted.

    Array of objects (ReturnSkuQtyInWMS)

    Items returned.

    comment
    string

    Staff's comment upon accept return.

    staff_name
    string <= 200 characters

    Name of the staff who accepted the return.

    If this is not provided, this will automatically be filled in as the name of the location.

    Responses

    Request samples

    Content type
    application/json
    {
    • "order_number": "3402340",
    • "rma_number": "R340",
    • "time": "2016-04-27T08:00:00Z",
    • "items_returned": [
      ],
    • "comment": "The items were damaged by courier.",
    • "staff_name": "Robb"
    }

    Response samples

    Content type
    application/json
    {
    • "error_messages": [
      ]
    }

    ERP Integration

    [v4] Get completed Sales and Returns Transactions

    This API is only applicable to clients who have opted for generating Refund Tlog on accept return. It is not applicable for those who have opted for generating Refund Tlog on refund approval.

    Details of all shipments and returns are available on the Comestri OMS Transaction Log API. Transactions are recorded at the point of revenue recognition; for shipments when stock has been set aside ready for the customer, and for returns when the return is accepted. Comestri OMS Transaction logs are typically translated by a middleware integration component, and send to the ERP or RMS system in the same format as used by the Point-of-Sale system.

    There are two ways to use the /tlog API:

    1. Query by time period with the parameters start_time and report_period
    2. Query by Shipment ID with the parameter shipment_id.

    Please note that:

    • These two sets of parameters are incompatible with each other and are mutually exclusive.
    • For querying with Shipment ID, only Sale Tlogs will be returned.

    query Parameters
    start_time
    string <time (ISO-8601 yyyy-MM-ddTHH:mm:ssZ)>

    Time in UTC from which to list transactions.

    This field is incompatible with shipment_id.

    Example: start_time=2016-04-27T08:00:00Z
    report_period
    integer

    Length of period to report, in minutes. Default value is 1,440 minutes; which is 24 hours.

    This field is incompatible with shipment_id.

    shipment_id
    string

    OMS shipment ID.

    This field is incompatible with start_time or report_period.

    Responses

    Response samples

    Content type
    application/json
    Example
    Example response with tlog queried with time period
    Example response with tlog queried with time period
    Example response with tlog queried with shipment ID
    Example response for tlog exempt
    Example response for shipment not ready to ship or collect yet
    Example response for tlog did not pass validation
    {
    • "start_time": "2016-04-27T08:00:00Z",
    • "report_period": 60,
    • "tx_count": 1,
    • "txs": [
      ]
    }

    [v5] Get completed Sales and Returns Transactions

    Details of all shipments and returns are available on the Comestri OMS Transaction Log API. Transactions are recorded at the point of revenue recognition; for shipments when stock has been set aside ready for the customer, and for returns when the return is accepted. Comestri OMS Transaction logs are typically translated by a middleware integration component, and send to the ERP or RMS system in the same format as used by the Point-of-Sale system.

    There are two ways to use the /tlog API:

    1. Query by time period with the parameters start_time and report_period
    2. Query by Shipment ID with the parameter shipment_id.

    Please note that:

    • These two sets of parameters are incompatible with each other and are mutually exclusive.
    • For querying with Shipment ID, only Sale Tlogs will be returned.

    query Parameters
    start_time
    string <time (ISO-8601 yyyy-MM-ddTHH:mm:ssZ)>

    Time in UTC from which to list transactions.

    This field is incompatible with shipment_id.

    Example: start_time=2016-04-27T08:00:00Z
    report_period
    integer

    Length of period to report, in minutes. Default value is 1,440 minutes; which is 24 hours.

    This field is incompatible with shipment_id.

    shipment_id
    string

    OMS shipment ID.

    This field is incompatible with start_time or report_period.

    Responses

    Response samples

    Content type
    application/json
    Example
    Example response with tlog queried with time period
    Example response with tlog queried with time period
    Example response with tlog queried with shipment ID
    Example response for tlog exempt
    Example response for shipment not ready to ship or collect yet
    Example response for tlog did not pass validation
    {
    • "start_time": "2016-04-27T08:00:00Z",
    • "report_period": 60,
    • "tx_count": 1,
    • "txs": [
      ]
    }

    POS Integration

    Shipment Picked Confirmation

    Confirm a shipment is picked with what skus are being picked and pick-failed.

    path Parameters
    shipmentId
    required
    string

    OMS shipment ID.

    Request Body schema: application/json
    picked_confirm_time
    required
    string <time (ISO-8601 yyyy-MM-ddTHH:mm:ssZ)>

    Time in UTC at which picking was completed. It will be shown in order history in OMS apps and Order Report.

    required
    Array of objects (SkuQtyInERP)

    The items picked. Note that items in skus and items in pick_failed_skus must add up to all the items of the collection order.

    object

    Necessary information about the pick fail action. These details are used in Pick Fail Report.

    Responses

    Request samples

    Content type
    application/json
    {
    • "picked_confirm_time": "2019-04-10T21:30:00Z",
    • "skus": [
      ],
    • "pick_fail_info": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "fields_with_syntax_errors": [
      ]
    }

    Confirm Collection

    Confirm a collection is collected by customer or hand delivered to customer.

    path Parameters
    shipmentId
    required
    string

    OMS shipment ID.

    Request Body schema: application/json
    collection_time
    required
    string <time (ISO-8601 yyyy-MM-ddTHH:mm:ssZ)>

    Time in UTC when the collection is collected by customer or hand delivered to customer. It will be shown in order history in OMS apps and Order Report.

    required
    Array of objects (SkuQtyInERP)

    The items collected. Items of the order that are not included in this array is consider non-collected which will in turn auto-trigger a return.

    comment
    string

    Staff’s comment upon customer collection or hand delivery to customer.

    Responses

    Request samples

    Content type
    application/json
    {
    • "collection_time": "2019-04-10T21:30:00Z",
    • "skus": [
      ],
    • "comment": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "fields_with_syntax_errors": [
      ]
    }

    Get POS Order Request [Draft Version]

    When an order is sent to OMS, OMS will allocate shipments to locations. When a location is a POS location, request may be received by a Retail System as a POS order. When split is allowed, an order will be divided into multiple shipments and sent to multiple POS locations as POS orders to the Retail System, to fulfil entire order. This API returns the payload that contains all the necessary information needed by a Retail System. Note that, such payload may also be received by a webhook mechanism.

    The provisional_tx returned in response may not be the eventual TLOG of the order.

    path Parameters
    shipmentId
    required
    string

    Identifier of the order to the retail system, which is actually the OMS shipment ID.

    Responses

    Response samples

    Content type
    application/json
    {
    • "order_id": "123-213-321",
    • "shipment_id": "123-213-321:S939",
    • "shipment_number": "S939",
    • "skus": [
      ],
    • "fulfilment_type": "shipping",
    • "given_name": "James",
    • "family_name": "Tennersby",
    • "phone": "85293405340",
    • "email": "customer@email.com",
    • "address": {
      },
    • "billing_address": {
      },
    • "location": "1001",
    • "packaging_type": "Gift",
    • "packaging_options": {
      },
    • "provisional_tx": {
      },
    • "additional_info": {
      },
    • "shipping_options": {
      }
    }

    Set POS Transaction ID

    Associate the POS Transaction ID with the OMS shipment.

    path Parameters
    shipmentId
    required
    string

    OMS Shipment ID.

    Request Body schema: application/json
    pos_transaction_id
    string <= 100 characters

    POS defined Transaction ID.

    Responses

    Request samples

    Content type
    application/json
    {
    • "pos_transaction_id": "PI45340"
    }

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Event Streams

    Inventory Updated Event

    Whenever there is a change on the available-to-sell quantities of SKUs, the update will be accumlated to sent as batches in events. The maximum number of records per event is 200 with maximum delay of 10 seconds.

    If the event is sent by a webhook mechanism, retry mechanisms will depend on client's configurations for timeout errors.

    Duplicate entries will be automatically filtered out and only the latest entry of the same web_sku_id will be sent.

    Request Body schema: application/json
    event_name
    required
    string

    The name of this event is "inventory-updated".

    total_number_of_entries
    integer

    Total number of entries returned.

    required
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    {
    • "event_name": "inventory-updated",
    • "total_number_of_entries": 1,
    • "entries": [
      ]
    }

    Response samples

    Content type
    application/json
    null

    Shipment Request Event

    This event is triggered once goods of a shipment are allocated to a location.

    If the event is sent by a webhook mechanism, retry mechanisms will depend on client's configurations for timeout errors.

    Request Body schema: application/json
    event_name
    required
    string

    The name of this event is "shipment-request".

    required
    object (ShipmentDetail)

    Responses

    Request samples

    Content type
    application/json
    {
    • "event_name": "shipment-request",
    • "shipment": {
      }
    }

    Response samples

    Content type
    application/json
    null

    Sale Confirmed Event

    This event is triggered when goods have been set aside and verified, and an invoice is generated for the customer. This is the time that OMS recognises the sale and posts the final sale transaction to the finance system. The event may be used in a number of integration scenarios, such as to post details of a sale to an ERP system, or to update the web platform to confirm that the goods are about to be dispatched.

    If the event is sent by a webhook mechanism, retry mechanisms will depend on client's configurations for timeout errors.

    Request Body schema: application/json
    event_name
    required
    string

    The name of this event is "sale-confirmed".

    required
    object (SalesTxV6)

    Responses

    Request samples

    Content type
    application/json
    {
    • "event_name": "sale-confirmed",
    • "tx": {
      }
    }

    Response samples

    Content type
    application/json
    null