Upsert an order with its customer and products

POST

https://api.agentpaid.io/api/v2/provision/

POST

/api/v2/provision/

import { PaidClient } from "@paid-ai/paid-node";
async function main() {
    const client = new PaidClient({
        token: "YOUR_TOKEN_HERE",
    });
    await client.orders.upsertOrderByExternalId({
        idempotencyKey: "deal_88213-2026-09-30T14:05:00Z",
        externalReference: {
            source: "standard",
            metadata: {
                crmDealId: "deal_88213",
                crmAccountId: "acct_4410",
            },
        },
        customer: {
            name: "Northwind Logistics",
            email: "billing@northwind.example",
            billingAddress: {
                line1: "200 Harbor Way",
                city: "Seattle",
                state: "WA",
                zipCode: "98101",
                country: "US",
            },
            externalId: "acct_4410",
        },
        order: {
            currency: "USD",
            startDate: new Date("2026-10-01T00:00:00.000Z"),
            name: "Northwind Logistics - Growth plan",
            externalId: "deal_88213",
            lines: [
                {
                    product: {
                        name: "Growth plan",
                        externalId: "growth_plan",
                        attributes: [
                            {
                                name: "Platform fee",
                                pricing: {
                                    chargeType: "recurring",
                                    pricePoints: {
                                        currency: "USD",
                                        unitPrice: 49900,
                                    },
                                    pricingModel: "perUnit",
                                    billingFrequency: "monthly",
                                    billingType: "advance",
                                },
                            },
                        ],
                    },
                    startDate: new Date("2026-10-01T00:00:00.000Z"),
                    externalId: "deal_88213_platform",
                },
                {
                    product: {
                        name: "Launch discount",
                        externalId: "launch_discount",
                        attributes: [
                            {
                                name: "Launch discount",
                                pricing: {
                                    chargeType: "recurring",
                                    pricePoints: {
                                        currency: "USD",
                                        unitPrice: 10000,
                                    },
                                    pricingModel: "perUnit",
                                    billingFrequency: "monthly",
                                    billingType: "advance",
                                },
                            },
                        ],
                    },
                    startDate: new Date("2026-10-01T00:00:00.000Z"),
                    endDate: new Date("2027-01-01T00:00:00.000Z"),
                    externalId: "deal_88213_launch_discount",
                    lineType: "CREDIT",
                },
            ],
        },
    });
}
main();

{
  "status": "created",
  "createdAt": "2026-09-30T14:05:12.000Z",
  "customer": {
    "id": "cus_7Qm2Lx9Pa",
    "provisionStatus": "created",
    "createdAt": "2026-09-30T14:05:12.000Z"
  },
  "order": {
    "id": "ord_3Vk8Ht1Zc",
    "lines": [
      {
        "id": "ordl_5Nw4Rb2Ye",
        "externalId": "deal_88213_platform",
        "provisionStatus": "created",
        "createdAt": "2026-09-30T14:05:12.000Z",
        "lineType": "STANDARD"
      },
      {
        "id": "ordl_8Jp6Ts3Qd",
        "externalId": "deal_88213_launch_discount",
        "provisionStatus": "created",
        "createdAt": "2026-09-30T14:05:12.000Z",
        "lineType": "CREDIT"
      }
    ],
    "provisionStatus": "created",
    "createdAt": "2026-09-30T14:05:12.000Z"
  }
}

Creates or updates a customer, an optional contact, the products on the order, and the order with its lines, in one call. Each record is matched by its externalId, so you can send the same deal again after it changes in your CRM. Returns 201 Created when the order is new, and 200 OK when an existing draft order with the same externalId was updated. Treat both as success. Re-provisioning an order that is already active returns 409 ORDER_ALREADY_ACTIVE; change an active order through the amendments API instead. Amounts are whole numbers in minor currency units (cents).

Authentication

AuthorizationBearer

API Key authentication using Bearer token

Request

Body

externalReferenceobjectRequired

customerobjectRequired

orderobjectRequired

The order, matched by externalId. Its lines are set from this payload each time you provision it. A draft order can have no lines; an active order needs at least one.

contactobjectOptional

Response headers

Idempotent-ReplayedstringOptional

true when this is the stored response of an earlier request with the same idempotency key. Absent otherwise.

Response

200

statusenum

Mirrors order.provisionStatus. created (HTTP 201): the order was created; updated (HTTP 200): an existing draft order with the same externalId was updated

Allowed values:

createdAtstring

customerobject

orderobject

contactobjectOptional

Errors

400

Bad Request Error

403

Forbidden Error

409

Conflict Error

500

Internal Server Error

Authentication

Headers

Request

Response headers

Response

Errors