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, and how to read the order recommendations, or requisitions, they come from.

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. Outbound Subjects lists the endpoints, and Webhooks the triggers.

GAINS decides whether an order line is a purchase, transfer or work order from where it ships from, unless the order type was overridden on the line in GAINS. 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.

An overridden line is returned with the order type set in GAINS.

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. To combine the endpoint with the webhook, see Pull or Push.

Size counts orders, each with all its lines; see Pagination.

Filters

Narrow what you read by approval code, tracking number, shipping or receiving location, or by extended data attributes that your GAINS representative has made available as filters. The API Reference describes each filter. Two points shape what you receive:

A filter on a line value must match every line of an order. An order with one line that does not match is left out entirely, not returned with fewer lines.
By default you receive only orders whose every line is approved. The approval code is a line value, so the default, approved (A), follows the rule above: an order with one line that is not yet approved is left out. To read it, name every code its lines carry, for example ApprovalCode=A,U.

See Receiving Extended Data for extended data filters.

Production orders

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. When an order's lines are on several production lines, the header ProductionLine reads multiple.
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.
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.

Requisitions

A requisition is a single order recommendation in GAINS: one item to be ordered from one shipping location into one receiving location, with its quantity, dates and cost. Buyers review requisitions and submit them; once submitted, they are grouped under a TrackingNumber and returned by the order endpoints above.

GET /replenishment/requisitions returns the recommendations line by line. Use it to see what GAINS recommends before buyers act on it, for example to report on open recommendations by buyer or vendor.

GET /api/v1/replenishment/requisitions?OrderType=purchase_order&ReceivingLocation=CHI01

{
  "DataType": "requisition",
  "Data": [
    {
      "OrderType": "purchase_order",
      "ItemCode": "ASM-7701",
      "ItemDescription": "Hub assembly, front",
      "ShippingLocation": "ACME",
      "ReceivingLocation": "CHI01",
      "ReceiveDate": "2026-12-01",
      "ReleaseDate": "2026-11-10",
      "DeliveryDate": "2026-11-28",
      "ApprovalCode": "U",
      "Quantity": 480,
      "Cost": 62.1,
      "LineComment": null,
      "OrderNumber": null,
      "BuyerCode": "JSMITH",
      "PreOrderCarryCost": 112.4,
      "DaysOverLeadTime": 0.0,
      "Weight": 6.2,
      "Volume": 0.05,
      "ConversionFactor": 12.0,
      "BundleCode": 3,
      "Department": "10",
      "Group": "HUB"
    }
  ],
  "Paging": {
    "NextCursor": null,
    "CurrentDataCount": 1
  }
}

Requisitions differ from orders in these ways:

Each record is one line. There is no order header, and Size counts lines.
GAINS decides the OrderType of each line as for orders: from where it ships from, unless the order type was overridden on the line in GAINS.
By default you receive the recommendations still under review, not approved ones, because that is what the endpoint is for. To include approved lines, name the approval codes you want.
A requisition does not say whether it has been submitted. It carries no TrackingNumber, so you cannot tell from the response whether a line is already part of an order. To process submitted orders, use the order endpoints or their webhooks.
There is no webhook for requisitions.

Requisitions can carry extended data on each line, and can be filtered by extended data attributes that your GAINS representative has made available as filters.

Webhooks

Enable the trigger for each order type you want to receive in your webhook configuration. 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 Configuring Webhooks, Webhook Filters and Delivery & Recovery, 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 Receiving Extended Data.

Errors

These endpoints return the statuses described in Errors & Retries.