Skip to content

Manual approval and the Economy fallback

By default, every order you create through the API is approved automatically, charged after a short delay, and sent to production. Two request features let you keep control of that moment: a per-order auto_approve field, and an approve operation to release a held order when you are ready.

This page also covers the Economy fallback - what happens when you request Economy shipping for a destination it cannot serve, and how to detect that before the order is charged.

Availability. Per-order auto_approve and the approve operation are enabled per team. Contact integration@gearment.com if your requests do not behave as described here.

Hold an order for manual approval

Send auto_approve: false when creating an order draft:

POST /api/v3/orders/draft
{
  "data": {
    "reference_id": "my-order-12345",
    "auto_approve": false,
    "...": "..."
  }
}
  • Omitted or true: current behavior, the order is approved automatically. Existing integrations do not change.
  • false: the draft is created and verified normally, but it is not auto-approved - it is never charged and never enters production until you approve it.
  • The field can only make approval stricter. If your team has disabled auto-approval in Settings, sending true does not override that.
  • The create response echoes the effective auto_approve value. Because unknown JSON fields are ignored during decoding, always assert on the echo - a misspelled field name would otherwise silently leave auto-approval on.

The legacy v2 form (act=order_create) accepts the same field and also accepts 0/1 or "0"/"1".

Approve a held order

POST /api/v3/orders/draft/{order_id}/approve

Legacy v2 form: POST https://api.gearment.com/v2/?act=order_approve with order_id in the body.

  • The operation is idempotent: approving an order that is already approved or awaiting checkout succeeds instead of failing, so a network retry is safe.
  • If verification (address, product matching, policy) is still running you get a failed-precondition error - wait a moment and retry.
  • After approval the normal flow resumes: the order is charged on the standard schedule and enters production.

The Economy fallback, and how to catch it

Economy (GOFO) does not cover every US ZIP code. When you request METHOD_ECONOMY for a destination outside coverage, the platform does not reject the order - it switches the order to Standard and prices it accordingly. If you sell with Economy rates, that switch changes your margins, so you want to know before the order is charged.

Two signals tell you, both on API v3:

  1. warnings in the Create Order Draft response. When a switch is coming, the create response includes a warning such as:
Shipping will be changed from Economy to Standard and priced accordingly:
the destination ZIP is outside active GoFo coverage.

The warning is best-effort - verification makes the final decision moments later - so treat it as an early signal, not the final state.

  1. shipping_substitution on the draft. After verification, read the draft (GET /api/v3/orders/draft/{order_id}) and check the shipping_substitution field and the current shipping method. This is the authoritative answer to "is this order actually going Economy?".
POST /api/v3/orders/draft        with auto_approve: false, METHOD_ECONOMY
  -> response.warnings mentions a switch?      early signal
GET  /api/v3/orders/draft/{id}   after verification
  -> shipping_substitution set / method changed?
     yes -> decide: approve at Standard pricing, or discard and re-create
     no  -> POST /api/v3/orders/draft/{id}/approve

Economy visibility on API v2

The legacy v2 surface carries the same signals:

  • act=order_create and act=order_label_create responses include a top-level warnings array with the same strings as the v3 create response. An empty array means no notices.
  • act=order_info and act=order_list order shapes include shipping_method (the effective lowercase code, e.g. standard) and shipping_substitution ({from, to, reason}, null when the order was not substituted). The existing fulfillment_notes prose is unchanged.

Existing v2 clients see two new fields (warnings: [], shipping_substitution: null) on responses they already receive. If your client validates responses against a strict schema, update the schema before relying on these fields.

v3 remains the recommended surface for new development; v3 credentials are issued in Developer Settings > API credentials.