Replenishment Orders

When buyers and planners submit orders in GAINS, GAINS Connect makes them available to your ERP or other system of record. This page explains how to receive submitted purchase, transfer, work and production orders, either pushed to you by webhook or read on demand from an endpoint.

Order types

Each order type has its own endpoint and its own webhook trigger, and both deliver the same order structure: an order header identified by its TrackingNumber, with its lines in LineItems.

GAINS decides whether an order line is a purchase, transfer or work order from where it ships from. Production orders are a separate kind:

• Purchase order: the ShippingLocation is a vendor, not one of your GAINS locations.
• Transfer order: the ShippingLocation is another of your locations. The header carries SenderName where a purchase order carries VendorName.
• Work order: the order is built at the location that receives it, so ShippingLocation and ReceivingLocation are the same.
• Production order: a production run submitted from Replenishment Scheduling or from Order Builder in production mode. It is scheduled on a ProductionLine instead of shipping from a location. See Production orders.

Choosing a webhook or the endpoint

Many integrations use both channels: the webhook to process orders as they arrive, and the endpoint to look up an order again by its TrackingNumber. Which channel to use, and how to combine them, is described in Pull or push.

Reading orders

Send a GET with any of the filters below. This request reads the purchase orders received into CHI01 from vendor ACME:

GET /api/v1/replenishment/purchase-orders?ReceivingLocation=CHI01&ShippingLocation=ACME&Size=50

{
  "DataType": "purchase_order",
  "Data": [
    {
      "TrackingNumber": 4821,
      "ShippingLocation": "ACME",
      "ReceivingLocation": "CHI01",
      "VendorName": "Acme Supplies",
      "ReleaseDate": "2026-05-21",
      "RequestedDeliveryDate": "2026-06-21",
      "SubmittedBy": "[email protected]",
      "UpdatedTime": "2026-05-21 11:00:00",
      "Documentation": "Consolidated weekly replenishment order.",
      "ContactName": "John Doe",
      "ContactEmail": "[email protected]",
      "ShipMethod": "land",
      "Address1": "123 Any St",
      "Address2": "Suite 400",
      "Address3": "Dock 7",
      "City": "Chicago",
      "State": "IL",
      "PostalCode": "60601",
      "Country": "US",
      "LineItems": [
        {
          "ItemCode": "ASM-7701",
          "ItemDescription": "Hub assembly, front",
          "Quantity": 480,
          "QuantityUnadjusted": 462,
          "Cost": 62.1,
          "LineComment": "Rounded up to pallet quantity",
          "ShippingLocation": "ACME",
          "ReceivingLocation": "CHI01",
          "OrderNumber": "PO-2026-004821",
          "OrderType": "REPLEN",
          "ReceiveDate": "2026-06-21",
          "DeliveryDate": "2026-06-19",
          "LineNumber": "1",
          "BuyerCode": "JSMITH",
          "ApprovalCode": "A",
          "ApprovedBy": "finley",
          "PreOrderCarryCost": 112.4,
          "DaysOverLeadTime": 0.0,
          "Weight": 6.2,
          "Volume": 0.05,
          "ConversionFactor": 12.0,
          "BundleCode": 3
        }
      ]
    }
  ],
  "Paging": {
    "NextCursor": null,
    "CurrentDataCount": 1
  }
}

The endpoint returns every submitted order of its type that GAINS currently holds and that matches your filters. It applies no date window and does not remember what you have already read, so the same order is returned on every call until GAINS no longer holds it. Record the TrackingNumber of each order you have processed, so that a scheduled pull does not create it twice.

Orders are returned newest first, in descending TrackingNumber order. Size counts orders, each with all its lines; see Pagination.

Filters

• Each parameter takes a comma-separated list of up to 10 values: ReceivingLocation=CHI01,DAL02. An order matches when it matches any value in the list.
• Different parameters combine with AND.
• A line-level filter must match every line. An order is returned only when all of its lines carry one of the requested ApprovalCode values and ship from one of the requested ShippingLocation values. An order with one line that does not match is left out entirely, not returned with fewer lines.
• Only approved orders are returned by default. Without ApprovalCode, the endpoint returns orders whose lines all carry approval code A. To read orders that carry another code, name every code you want: ApprovalCode=A,U.
• The header shows multiple when lines differ. When an order's lines ship from different locations, the header ShippingLocation reads multiple. Filter on ShippingLocation to find such orders by their lines.

You can also filter on extended data attributes that your GAINS representative has made available as filters. See Extended Data - Outbound.

Production orders

🚧

GAINS X version

Production orders need a minimum GAINS X version, stated on the GET /replenishment/production-orders reference page. On an earlier version the endpoint answers 426 (see When your version is too old (426)).

A production order groups the production runs submitted under one TrackingNumber. It differs from the other order types in these ways:

• The production line takes the place of the shipping location. Filter with ProductionLine instead of ShippingLocation; it must match every line, as above.
• ReceivingLocation is the plant. When an order's lines go to several plants, the header ReceivingLocation reads multiple, and such an order matches no ReceivingLocation filter.
• Lines carry the schedule of the run, for example ScheduledStartDate and ScheduledEndDate. Quantities are in stocking units.
• Header details may be empty. On orders submitted from Replenishment Scheduling, header fields such as the contact and the address fields are null.
• OrderNumber reads NONE until GAINS records an order number against the line. Identify the order by TrackingNumber.
• The approval code can differ. Orders submitted from Replenishment Scheduling can carry an approval code other than A. Name every code you want to read, for example ApprovalCode=A,U.

Webhooks

Enable the trigger for each order type you want to receive in your webhook settings. Each delivery carries the same orders and fields as the endpoint, without Paging.

A trigger is not all-or-nothing: give it a filter, and GAINS sends only the orders that match. For example, to send only orders for two receiving locations to one destination:

{
  "Triggers": {
    "POSubmit": {
      "Enabled": true,
      "Filter": "ReceivingLocation IN ('CHI01', 'DAL02')"
    }
  }
}

Filters can use the fields of the payload and your extended data (ExtendedData.<ApiLabel>). Combined with several webhook destinations, they let you route orders for different locations or vendors to different systems. You can also resend a delivery, or the orders of one TrackingNumber, with POST /webhook/resend.

See Webhooks for setting up destinations, the filter syntax and retries, and Webhook Payload Samples for a sample payload of each order type.

Extended data

Orders can carry extended data on the order header and on each line, on both the endpoint and the webhook. See Extended Data - Outbound.

Errors

See Errors Handling & Exceptions for the error response body.

Related

• To read order recommendations line by line, whether or not they have been submitted, use GET /replenishment/requisitions.
• Outbound Overview: Pull or Push
• Webhooks
• Pagination
• Extended Data - Outbound