Skip to main content
View as Markdown

Orders

Use this reference for exact Orders API request attributes, response envelopes, object shape, and examples. For lifecycle, checkout patterns, ID boundaries, and fulfillment behavior, start with the Orders product guide.

The order object

Every single-order endpoint returns an order envelope. Page returns the same object inside orders. Optional fields are omitted until they exist; treat omission as absence, not as an empty value. When an order has refunds, refunds contains every refund in newest-first order and each entry uses the complete shared refund object. Orders without refunds omit the attribute entirely; they do not return an empty or null refunds value.

Properties​

TypeScript SDK responseOrderv12.0.0
POST/orders/create

Create an order

Create a new order for a first-time or returning customer, and decide whether to charge it now or later. Product line items can be fully inline, or they can reuse products and prices you already keep in your catalog.

Available through MCP

AI clients can use create_order for this operation. Confirmed MCP actions still require explicit form confirmation before Inttegro changes state.

The MCP create_order tool creates orders from existing customer, product, and price IDs and never executes payment.

Note

Clients should treat the published route in this reference as authoritative and should not construct alternative order-creation paths.

Rules​

Required attributes​

TypeScript SDK requestCreateOrderRequestv12.0.0

Product line item shapes​

Use the shape that matches how you manage your catalog and pricing:

Define the product and its price directly on this order.

{
  lineItems: [
    {
      type: Inttegro.LineItemTypes.Product,
      product: {
        name: "Utility Sneakers",
        type: Inttegro.ProductTypes.Physical,
        quantity: 1,
        price: {
          currency: "ghs",
          value: 20000,
        },
      },
    },
  ],
}

When you reference lineItems[].product.productId, Inttegro snapshots the product data onto the order at creation time. Later edits to the catalog product or price do not rewrite an order that already exists. You can also mix catalog-backed and inline product line items in the same order, as long as every line item uses the same currency.

The complete HTTP examples below use inline product data. If you already keep products and prices in your catalog, replace the lineItems[].product payload with either catalog-backed shape shown above.

Optional attributes​

TypeScript SDK requestCreateOrderRequestv12.0.0
  • requestMetaRequestMetaRequest-specific controls that do not change the order being created.Click or tap to expand
    • Name
      idempotencyKey
      Type
      string
      Description
      Optional request key for this logical order creation.
  • Name
    paymentMethodId
    Type
    string
    Description

    ID of a saved payment method to charge. Only works with customerId—the method must belong to that customer.

  • Name
    receiptNumber
    Type
    string
    Description

    Optional merchant-supplied receipt reference for reconciliation. Inttegro trims whitespace, applies the same configured length validation used for number, and does not enforce uniqueness.

  • Name
    statementDescriptor
    Type
    string
    Description

    Exact descriptor shown on the customer's bank or mobile money statement. Mutually exclusive with statementDescriptorPrefix.

  • Name
    statementDescriptorPrefix
    Type
    string
    Description

    Static prefix, between 2 and 10 characters, used to build the descriptor as prefix*order_id. Inttegro appends enough characters from the generated order ID to fit the final descriptor limit.

  • paymentMethodDataPaymentMethodDataInline payment details for new payment instruments.Click or tap to expand
  • Name
    executePayment
    Type
    boolean
    Description

    Whether to charge the order immediately. Defaults to false—you'll call /orders/pay later.

  • Name
    finalize
    Type
    boolean
    Description

    Set to true to seal the order and generate its hosted invoice. When omitted or false, an order without executable payment details remains a draft and its response omits invoice.

  • invoiceSettingsInvoiceSettingsOptional customer-facing invoice content.Click or tap to expand
    • Name
      customData
      Type
      CustomData
      View custom_data detailsClick or tap to expand
      String key-value data attached to the invoice.
    • Name
      memo
      Type
      string
      Description
      Customer-facing invoice note.
    • Name
      number
      Type
      string
      Description
      Invoice number.
  • Name
    paymentDueAfter
    Type
    Date
    Description

    RFC 3339 timestamp for when payment is due. The order response exposes it as paymentDueAt when set.

  • customDataCustomDataClick or tap to expand

    Arbitrary string key-value pairs for application-specific needs. Attach internal order IDs, fulfillment workflows, tracking identifiers, or any metadata your system requires. Maximum size when serialized: 25 KB. See the Custom Data guide for best practices.

  • checkoutSettings{ … }Checkout configuration for this order. Strongly recommended to provide both checkoutSettings.redirectUrl and checkoutSettings.cancelUrl for a delightful customer experience.Click or tap to expand
    • Name
      redirectUrl
      Type
      string
      Description
      URL where customers land after completing payment. Include order tracking parameters to show order status and next steps.
    • Name
      cancelUrl
      Type
      string
      Description
      URL where customers land if they abandon checkout without paying. Use this to show incomplete order details or offer alternative payment methods.
  • billingDetailsBillingDetailsContact info for invoicing and receipt delivery.Click or tap to expand
    • Name
      name
      Type
      string
      Description
      Billing contact name.
    • Name
      emailAddress
      Type
      string
      Description
      Billing email address.
    • Name
      phoneNumber
      Type
      string
      Description
      Billing phone number.
    • Name
      address
      Type
      Address
      View address attributesClick or tap to expand
      Optional postal address for invoices.
      • Name
        name
        Type
        string
        Description
        Recipient name if different from customer.
      • Name
        phoneNumber
        Type
        string
        Description
        Contact phone for delivery or verification.
      • Name
        line1
        Type
        string
        Description
        Street address line 1.
      • Name
        line2
        Type
        string
        Description
        Street address line 2 (optional).
      • Name
        city
        Type
        string
        Description
        City or town.
      • Name
        region
        Type
        string
        Description
        State, province, or region.
      • Name
        country
        Type
        string
        Description
        Country name.
      • Name
        postCode
        Type
        string
        Description
        Postal or ZIP code.
  • shippingShippingOptional shipping destination for physical fulfillment.Click or tap to expand
    • Name
      address
      Type
      Address
      View address attributesClick or tap to expand
      Where the package should go. Uses Address.
      • Name
        name
        Type
        string
        Description
        Recipient name.
      • Name
        phoneNumber
        Type
        string
        Description
        Phone number for delivery coordination.
      • Name
        line1
        Type
        string
        Description
        Street address line 1.
      • Name
        line2
        Type
        string
        Description
        Street address line 2 (optional).
      • Name
        city
        Type
        string
        Description
        City or town.
      • Name
        region
        Type
        string
        Description
        State, province, or region.
      • Name
        country
        Type
        string
        Description
        Country name.
      • Name
        postCode
        Type
        string
        Description
        Postal or ZIP code.
  • payoutSettingsOrderPayoutSettingsOrder-specific payout configuration. Overrides your application-level payout settings for this order—useful for marketplace scenarios where different orders route to different sellers.Click or tap to expand
    • Name
      destination
      Type
      { … }
      View destination attributesClick or tap to expand
      Where funds from this order should be paid out.
      • Name
        financialAccountId
        Type
        string
        Description
        ID of an existing financial account to receive the payout. The account must exist and have push capability enabled. Create financial accounts via the dashboard or [Financial Accounts API](/api/financial-accounts).
    • Name
      enableFx
      Type
      boolean
      Description
      Optional compatibility flag. Omit it or set it to false; true is rejected because cross-currency payouts are not currently available.

Request

POST/orders/create
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.create({
  requestMeta: {
    idempotencyKey: "order_checkout_ORDER-NUMBER-2",
  },
  number: "ORDER-NUMBER-2",
  receiptNumber: "RCPT-NUMBER-2",
  statementDescriptor: "STMTDESC",
  executePayment: true,
  finalize: true,
  checkoutSettings: {
    redirectUrl: "https://google.com/thank-you",
    cancelUrl: "https://google.com/order-cancelled",
  },
  customerData: {
    name: "Customer Name",
    emailAddress: "[email protected]",
    phoneNumber: "+233242058841",
  },
  paymentMethodData: {
    type: Inttegro.PaymentMethodTypes.MobileMoney,
    mobileMoney: {
      network: Inttegro.MobileMoneyNetworks.MTN,
      accountNumber: "0242057831",
    },
  },
  lineItems: [
    {
      type: Inttegro.LineItemTypes.Product,
      product: {
        type: Inttegro.ProductTypes.Physical,
        name: "Utility Sneakers",
        quantity: 1,
        price: {
          currency: "ghs",
          value: 20000,
        },
      },
    },
  ],
  billingDetails: {
    name: "Customer Name",
    emailAddress: "[email protected]",
    phoneNumber: "+233242058841",
    address: {
      name: "Customer Name",
      phoneNumber: "+233242058841",
      line1: "23 Adenta High Street",
      town: "Accra",
      region: "Greater Accra",
      country: "GH",
    },
  },
})

Response

SDK versionv12.0.0
OrderResponse {
  order: { … },
}
POST/orders/search

Search orders

Search orders by customer, invoice, or other remembered text, and narrow the result set by status. Results are discovery summaries: use the returned order ID with Lookup an order before fulfillment, collection, cancellation, or any other state-dependent action.

Request attributes​

TypeScript SDK requestResourceSearchRequestv12.0.0
  • Name
    cursor
    Type
    string
    Description

    Opaque continuation cursor returned by the previous page. Replay the same request and add this value for the next page.

  • facetsResourceSearchFacet[]Fields to group and count. This route accepts only status.Click or tap to expand
    • Name
      field
      Type
      string
      Required
      required
      Description
      Route-local field name. Use status.
    • Name
      limit
      Type
      number
      Description
      Maximum buckets, from 1 through 50. Defaults to 10.
  • filtersResourceSearchFilter[]Exact status constraints.Click or tap to expand
    • Name
      field
      Type
      string
      Required
      required
      Description
      Route-local field name. Use status.
    • Name
      operator
      Type
      ResourceSearchOperator
      Required
      required
      Description
      eq for one value or in for any supplied value.
    • Name
      values
      Type
      string[]
      Required
      required
      Description
      One value for eq; one through 20 values for in.
  • Name
    pageSize
    Type
    number
    Description

    Results per page, from 1 through 100. Defaults to 20.

  • sortResourceSearchSortResult ordering.Click or tap to expand
  • Name
    text
    Type
    string
    Description

    Search text, from 1 through 512 characters. Supply search text, exact filters, or both.

Response​

Returns a typed search page with discovery summaries, requested facet counts, page and total counts, an optional nextCursor, and freshness metadata. Read the canonical order before acting on a result.

Request

POST/orders/search
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})

const request: Inttegro.ResourceSearchRequest = {
  text: "INV-1042",
}
const page = await inttegro.orders.search(request)

Response excerpt

SDK versionv12.0.0
SearchResponse {
  search: { … },
}
POST/orders/pay

Pay for an order

Start or retry payment on an existing order without recreating it. This operation finalizes an open draft before collection. Four ways to use it:

  • Already has a payment method: Just send orderId—we'll charge the attached method.
  • Swap to a different saved method: Send orderId and paymentMethodId.
  • Use a new payment method once: Send orderId and paymentMethodData.
  • Offline payment: Send orderId and set paidOutOfBand to true—this marks the payment as received outside Inttegro (cash, bank transfer, check). Complete the order separately when fulfillment is done.

Rules​

Required attributes​

TypeScript SDK requestPayOrderv12.0.0
  • Name
    orderId
    Type
    string
    Description

    ID of the order to pay.

Optional attributes​

TypeScript SDK requestPayOrderv12.0.0

Request

POST/orders/pay
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.pay({
  orderId: "or_JoPtqOmsjgZKwkPvqTrqGsopu07wfC7ttoWqmfwt",
  paymentMethodData: {
    type: Inttegro.PaymentMethodTypes.MobileMoney,
    mobileMoney: {
      network: Inttegro.MobileMoneyNetworks.MTN,
      accountNumber: "0544998605",
    },
  },
})

Response

SDK versionv12.0.0
OrderResponse {
  order: { … },
}
POST/orders/confirm_payment

Confirm a payment

Submit the confirmation token for a specific payment and confirmation request. Read paymentId from payment.id and confirmationId from payment.nextAction.confirmPayment.id in the preceding create, pay, or request-confirmation response. The response always uses the order envelope; an actionable error can include both order and an error object.

Required attributes​

TypeScript SDK requestConfirmPaymentRequestv12.0.0
  • Name
    confirmationId
    Type
    string
    Description

    ID of the confirmation request that issued the token.

  • Name
    orderId
    Type
    string
    Description

    ID of the order being paid.

  • Name
    paymentId
    Type
    string
    Description

    ID of the payment attached to the order.

  • Name
    token
    Type
    string
    Description

    Confirmation token supplied by the customer.

Request

POST/orders/confirm_payment
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.confirmPayment({
  confirmationId: "otc_req_8Ks2Vn",
  orderId: "or_JoPtqOmsjgZKwkPvqTrqGsopu07wfC7ttoWqmfwt",
  paymentId: "py_3deNYy",
  token: "302673",
})

Response

SDK versionv12.0.0
OrderResponse {
  order: { … },
}
POST/orders/request_confirmation

Request confirmation

Some payment methods—especially mobile money—require the customer to confirm with an OTP. Call this to send (or resend) the confirmation token.

Request

POST/orders/request_confirmation
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.requestConfirmation({
  orderId: "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi",
})

Response

SDK versionv12.0.0
OrderResponse {
  order: { … },
}
POST/orders/update

Update an order

Update mutable fields on an existing order and get back the same response shape as Lookup an order. Use this endpoint for three distinct cases: revising an open draft, reopening a sealed order so it becomes editable again, or applying changes and resealing in the same request.

What you can change​

Rules​

  • Include at least one mutable field besides orderId.
  • lineItems is a full replacement field, not a sparse merge, and it cannot be empty when provided.
  • If you replace lineItems, the updated order must stay within the current order limits: at most 64 line items, up to 100,000 for "ghs", and up to 50,000 for all other supported currencies. Contact support if you need these limits increased.
  • paymentMethodId, paymentMethodData, and clearPaymentMethod are mutually exclusive.
  • paymentMethodData currently supports only Inttegro.PaymentMethodTypes.MobileMoney for order updates.
  • Completed, paid, canceled, and expired orders cannot be updated.
  • customData is metadata-only. Updating it does not require reopen / reseal by itself.
  • Omit receiptNumber to leave it unchanged. When provided, Inttegro trims it and requires a different non-empty value within the same configured length limits as number. It cannot be cleared once set, and receipt numbers are not unique.
  • If payment confirmation or execution has already started, Inttegro rejects edits that change economics, payment configuration, or require reopening the order.
  • When mutating seal-sensitive fields on a sealed order, you must provide finalize explicitly:
    • finalize set to false reopens the order and leaves it editable.
    • finalize set to true applies the changes and seals the order again in the same request.

Required attributes​

TypeScript SDK requestUpdateOrderRequestv12.0.0
  • Name
    orderId
    Type
    string
    Description

    The unique identifier of the order to update.

Optional attributes​

TypeScript SDK requestUpdateOrderRequestv12.0.0

Response shape​

  • Returns the same order object as Lookup an order.
  • If finalize is false, sealedAt and invoice are cleared until the order is sealed again.
  • If finalize is true, Inttegro returns the regenerated invoice and the updated payment amount.
  • The returned order object includes top-level customData when present.
  • The returned order object includes top-level receiptNumber when set.

Request

POST/orders/update
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.update({
  orderId: "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
  receiptNumber: "RCPT-2025-041-REV1",
  lineItems: [
    {
      type: Inttegro.LineItemTypes.Product,
      product: {
        name: "Quarterly support retainer",
        type: Inttegro.ProductTypes.Digital,
        price: {
          currency: "ghs",
          value: 15000,
        },
        quantity: 1,
      },
    },
    {
      type: Inttegro.LineItemTypes.Fee,
      fee: {
        label: "Service fee",
        amount: {
          currency: "ghs",
          value: 500,
        },
      },
    },
  ],
  statementDescriptor: "ORDER REVISION",
  customData: {
    channel: "dashboard",
    edited_by: "ops",
  },
  finalize: true,
})

Response

SDK versionv12.0.0
OrderResponse {
  order: { … },
}
POST/orders/finalize

Finalize an order

Finalize a draft to seal its line items and total for payment. The response exposes the hosted invoice URLs you can share with the customer.

What finalization means​

Finalizing an order is the transition from Inttegro.OrderStatuses.Preparing to Inttegro.OrderStatuses.RequiresPayment. Before finalization, you can replace line items and change supported order or payment settings. After finalization:

  • Line items freeze: No additions, removals, or quantity changes unless you later reopen the order with Update an order
  • Totals lock: The amount due becomes fixed until the order is reopened
  • Invoice generates: A viewable invoice with web and PDF formats
  • Checkout activates: The hosted payment page becomes accessible
  • Payment readiness: The order can accept payment attempts

Use this endpoint when you've finished building the cart and want to present it to the customer for payment. The response includes invoice URLs and the sealedAt timestamp marking when the order was finalized. Finalizing an already sealed order is safe and leaves the existing state unchanged.

Required attributes​

TypeScript SDK requestFinalizeOrderRequestv12.0.0
  • Name
    orderId
    Type
    string
    Description

    The unique identifier of the order to finalize.

Request

POST/orders/finalize
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.finalize({
  orderId: "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
})

Response

SDK versionv12.0.0
OrderResponse {
  order: { … },
}
POST/orders/send_invoice

Send an invoice

Send an order's hosted invoice link to its customer. Inttegro uses the contact details saved for that customer: when both a phone number and email address are available, it sends the link by SMS and email; otherwise it uses the available channel.

The order must be finalized and its invoice must be ready to send. For a draft order, first use Finalize an order.

Available through MCP

AI clients can use send_order_invoice for this operation. Confirmed MCP actions still require explicit form confirmation before Inttegro changes state.

Request body​

TypeScript SDK requestOrderDocumentDeliveryRequestv12.0.0
  • Name
    orderId
    Type
    string
    Required
    required
    Description

    The order whose hosted invoice link should be sent.

Response​

Returns the current order plus a delivery object. If one channel succeeds and another fails, the endpoint may return HTTP 207 with both delivery.sentChannels and delivery.failedChannels.

TypeScript SDK responseOrderDocumentDeliveryResultv12.0.0

Invoice delivery can return draft_mode_order_has_no_invoice, order_delivery_auth_failed, order_delivery_contact_missing, order_delivery_failed, or order_not_found.

Request

POST/orders/send_invoice
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.sendInvoice({
  orderId: "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
})

Response

SDK versionv12.0.0
Response {
  order: { … },
  delivery: { … },
}
POST/orders/send_receipt

Send a receipt

Send the hosted receipt link for an existing paid order. Inttegro uses the same fan-out rules as invoice delivery: SMS and email when both customer contacts exist, otherwise whichever contact method is available.

Receipt delivery is available only after the order is paid. The link points to the hosted receipt path, such as /invoices/{order_id}/receipt; do not use the invoice PDF path for receipt delivery.

Available through MCP

AI clients can use send_order_receipt for this operation. Confirmed MCP actions still require explicit form confirmation before Inttegro changes state.

Request body​

TypeScript SDK requestOrderDocumentDeliveryRequestv12.0.0
  • Name
    orderId
    Type
    string
    Required
    required
    Description

    The paid order whose hosted receipt link should be sent.

Response​

Returns the current order plus a delivery object. If one channel succeeds and another fails, the endpoint may return HTTP 207 with both delivery.sentChannels and delivery.failedChannels.

TypeScript SDK responseOrderDocumentDeliveryResultv12.0.0

Receipt delivery can return order_delivery_auth_failed, order_delivery_contact_missing, order_delivery_failed, order_not_found, or order_receipt_missing.

Request

POST/orders/send_receipt
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.sendReceipt({
  orderId: "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
})

Response

SDK versionv12.0.0
Response {
  order: { … },
  delivery: { … },
}
POST/orders/complete

Complete an order

Mark an order as completed when the customer has received their items or you've fulfilled the service. This transitions the order to the Inttegro.OrderStatuses.Completed state, indicating the transaction is fully satisfied.

When to complete orders​

Complete an order when:

  • Physical goods: Items have been delivered or picked up
  • Digital products: Files have been downloaded or access granted
  • Services: Work has been performed and accepted
  • Out-of-band payments: Cash, check, or bank transfer received offline

The order must have a successful payment before completion, unless you're marking an offline payment by setting paidOutOfBand to true.

Out-of-band payments​

If the customer paid outside Inttegro (cash, bank transfer, check), set paidOutOfBand to true. This marks both the payment and order as complete in a single operation. The payment gets marked as paid offline before the order is completed.

Use this for:

  • Cash on delivery scenarios
  • Bank transfer confirmations
  • Check payments that cleared
  • Any payment method outside the Inttegro platform

Required attributes​

TypeScript SDK requestCompleteOrderRequestv12.0.0
  • Name
    orderId
    Type
    string
    Description

    The unique identifier of the order to complete.

Optional attributes​

TypeScript SDK requestCompleteOrderRequestv12.0.0
  • Name
    paidOutOfBand
    Type
    boolean
    Description

    Set to true if payment was received outside Inttegro (cash, bank transfer, check). When true, the payment is marked as paid offline before completing the order. Defaults to false, which requires the payment to already be in Inttegro.PaymentStatuses.Paid status.

Request

POST/orders/complete
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.complete({
  orderId: "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
})

Response

SDK versionv12.0.0
OrderResponse {
  order: { … },
}
POST/orders/lookup

Lookup an order

Fetch the current order and nested payment state by ID. A missing or inaccessible order returns HTTP 400 with error code order_not_found; use the error object rather than checking for 404.

Available through MCP

AI clients can use get_order, prepare_order_payment, get_refund_options, pay_order or create_refund for this operation. Confirmed MCP actions still require explicit form confirmation before Inttegro changes state.

Required attributes​

TypeScript SDK requestLookupOrderRequestv12.0.0
  • Name
    orderId
    Type
    string
    Description

    Order ID from the creation response.

Request

POST/orders/lookup
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.lookup({
  orderId: "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
})

Response excerpt

SDK versionv12.0.0
OrderResponse {
  order: { … },
}
POST/orders/cancel

Cancel an order

Cancel an unpaid, unfulfilled order. Cancellation moves the order to Inttegro.OrderStatuses.Canceled and records the time of the transition. The reason and executeRefund inputs are retained as cancellation evidence; they are not returned as order fields.

Paid, completed, expired, and already canceled orders cannot be canceled. Cancellation does not currently void, reverse, or refund an attached payment. If money moved, use the refund flow separately and verify its result before treating funds as returned.

Warning
executeRefund is accepted for contract compatibility but currently records intent only. Setting it to true does not execute a refund.

Request attributes​

TypeScript SDK requestCancelOrderRequestv12.0.0
  • Name
    executeRefund
    Type
    boolean
    Description

    Records that refund execution was requested as part of the cancellation. It defaults to false and does not currently move funds; use the refund flow separately.

  • Name
    orderId
    Type
    string
    Description

    The typed ID of the order to cancel (e.g. or_abc123).

  • Name
    reason
    Type
    string
    Description

    Optional free-text explanation for the cancellation. Recorded on the order for audit purposes. Defaults to "unknown" if not provided. Common values: "customer_request", "fraud", "inventory_unavailable", "duplicate".

Request

POST/orders/cancel
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.cancel({
  orderId: "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi",
  reason: "customer_request",
  executeRefund: false,
})

Response

SDK versionv12.0.0
OrderResponse {
  order: { … },
}
POST/orders/page

Page through orders

Retrieve a paginated list of your most recent orders. Orders are sorted by orders[].initiatedAt in descending order, so page 0 contains the freshest activity and subsequent pages step back in time.

Provide customerId to scope the page to a single customer. Omit customerId to browse all recent orders.

pageSize is required. pageNumber is zero-based, defaults to 0, and accepts values from 0 through 10. An unknown or inaccessible customer filter returns HTTP 400; a temporary page lookup failure returns 503 and can be retried unchanged.

Available through MCP

AI clients can use list_orders for this operation. MCP read tools return minimized business data and do not change Inttegro state.

Required attributes​

TypeScript SDK requestPageOrdersRequestv12.0.0
  • Name
    pageSize
    Type
    number
    Description

    Number of orders requested per page. Must be between 1 and 256.

Optional attributes​

TypeScript SDK requestPageOrdersRequestv12.0.0
  • Name
    customerId
    Type
    string
    Description

    Optional customer ID to scope the page to one buyer's orders only.

  • Name
    pageNumber
    Type
    number
    Description

    Zero-based page index from 0 through 10. Defaults to 0 when omitted.

Response shape​

  • Top-level page object includes number, size, and an orders array.
  • Each array entry uses the complete shared order object, not a condensed summary.
  • Orders created through a purchase intent include orders[].createdFrom attribution when available. Public API-key requests cannot filter pages by that attribution.
  • Optional fields are omitted when unavailable. Paid or completed orders can include payment.receipt; the API does not add a line_item_group.products_count summary field.
  • When you filter by customerId, every returned order belongs to that customer.

Request

POST/orders/page
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.page({
  pageNumber: 0,
  pageSize: 25,
})

Response excerpt

SDK versionv12.0.0
PageResponse {
  page: { … },
}