> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://docs.paid.ai/v-2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paid.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paid.ai/_mcp/server.

# Upsert an order with its customer and products

POST https://api.agentpaid.io/api/v2/provision/
Content-Type: application/json

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. A 503 `BILLING_UNAVAILABLE` means draft pricing could not be confirmed and any newly created draft was deleted; send the same request again with the same idempotency key. If a new draft is retained, returns 409 `ORDER_RETAINED` with its order id and externalId in `details`. Retrieve that order and check its state instead of repeating creation. Amounts are whole numbers in minor currency units (cents).

Reference: https://docs.paid.ai/api-reference/api-reference/orders/upsert-order-by-external-id

## Authentication

- `Authorization` header (bearer token, required) — API Key authentication using Bearer token

## Request

### Headers

- `idempotency-key` (string, required) — A unique key for this provision, such as the source record ID plus its last-modified time. Retrying with the same key and body returns the stored response with the `Idempotent-Replayed: true` header. The same key with a different body returns 409 `IDEMPOTENCY_KEY_CONFLICT`.

### Body (application/json)

This endpoint expects a ProvisionRequest.

- `externalReference` (ProvisionExternalReference, required)
- `customer` (ProvisionCustomer, required)
- `order` (ProvisionOrder, required) — 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.
- `contact` (ProvisionContact, optional)

## Response

### 200

200

- `status` (enum, required) — 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: `created`, `updated`
- `createdAt` (string, required)
- `customer` (ProvisionCreatedCustomer, required)
- `order` (ProvisionCreatedOrder, required)
- `contact` (ProvisionCreatedContact, optional)

### 201

201

- `status` (enum, required) — 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: `created`, `updated`
- `createdAt` (string, required)
- `customer` (ProvisionCreatedCustomer, required)
- `order` (ProvisionCreatedOrder, required)
- `contact` (ProvisionCreatedContact, optional)

## Errors

### 400 Bad Request Error

400

- `error` (string, required)
- `code` (string, optional)
- `details` (string, optional)

### 403 Forbidden Error

403

- `error` (string, required)
- `code` (string, optional)
- `details` (string, optional)

### 409 Conflict Error

409

- `error` (string, required)
- `code` (string, optional)
- `details` (string, optional)

### 500 Internal Server Error

500

- `error` (string, required)
- `code` (string, optional)
- `details` (string, optional)

### 503 Service Unavailable Error

503

- `error` (string, required)
- `code` (string, optional)
- `details` (string, optional)

## Types

### ProvisionExternalReference

- `source` (enum, required) — The system that sends the provision. Use `standard` for an integration you build yourself: it has no source-specific behaviour, and neither do `hubspot` and `salesbricks`. With `salesforce`, a recurring or seat-based line price is the value for the whole line term, and Paid bills it once, as one billing period that spans the line. For that reason `salesforce` cannot be combined with `order.billingFrequencyOverride`.
  - Allowed values: `salesforce`, `hubspot`, `salesbricks`, `standard`
- `metadata` (map from string to any, optional) — Free-form details from the source system, such as its record IDs. Paid stores the whole `externalReference` object, `source` included, on the order's `metadata` under the `externalReference` key. Each provision of the order replaces it, and other `metadata` keys are kept.

### ProvisionCustomer

- `name` (string, required)
- `externalId` (string, required)
- `legalName` (string, optional, nullable)
- `email` (string, optional)
- `phone` (string, optional)
- `website` (string, optional)
- `billingAddress` (CustomerBillingAddressInput, optional)
- `creationState` (enum, optional, default: active) — The customer state, `draft` or `active`. Defaults to `active`.
  - Allowed values: `draft`, `active`
- `vatNumber` (string, optional, nullable)
- `metadata` (map from string to any, optional, nullable)
- `defaultCurrency` (string, optional)

### ProvisionOrder

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.

- `currency` (string, required) — Currency code for the order, such as `USD`. A price point can set its own currency.
- `startDate` (datetime, required)
- `externalId` (string, required)
- `lines` (list of ProvisionOrderLine, required)
- `endDate` (datetime, optional)
- `status` (enum, optional, default: active) — Defaults to `active`, which activates the order and starts billing. Send `draft` to create or update the order without billing it; you can provision it again later with `active`. An active order cannot go back to `draft`.
  - Allowed values: `draft`, `active`
- `billingAnchor` (integer, optional, nullable)
- `billingCustomerExternalId` (string, optional)
- `billingContactExternalIds` (list of string, optional)
- `paymentTerms` (enum, optional)
  - Allowed values: `DueOnReceipt`, `Net15`, `Net30`, `Net45`, `Net60`, `Net90`
- `name` (string, optional)
- `billingFrequencyOverride` (ProvisionBillingFrequencyOverride, optional)
- `historicalReplayUntil` (datetime, optional) — For migrating an order that another system has already billed. ISO 8601 timestamp in UTC. Paid creates no invoices or payments for billing cycles that fall due on or before this time, and bills normally after it. Use it with a past `startDate` so the order does not bill again for periods the other system already billed.

### ProvisionContact

- `externalId` (string, required)
- `firstName` (string, optional)
- `lastName` (string, optional)
- `email` (string, optional)
- `phone` (string, optional, nullable)
- `billingAddress` (ContactBillingAddress, optional)
- `roles` (list of enum, optional)
  - Allowed values: `BILLING`, `ACCOUNTS_PAYABLE`

### ProvisionCreatedCustomer

- `id` (string, required)
- `provisionStatus` (enum, required) — created: the entity was created; updated: the entity was updated
  - Allowed values: `created`, `updated`
- `createdAt` (datetime, required)

### ProvisionCreatedOrder

- `id` (string, required)
- `lines` (list of ProvisionCreatedOrderLine, required)
- `provisionStatus` (enum, required) — created: the entity was created; updated: the entity was updated
  - Allowed values: `created`, `updated`
- `createdAt` (datetime, required)
- `billingFrequencyOverride` (ProvisionBillingFrequencyOverride, optional)

### ProvisionCreatedContact

- `id` (string, required)
- `provisionStatus` (enum, required) — created: the entity was created; updated: the entity was updated
  - Allowed values: `created`, `updated`
- `createdAt` (datetime, required)

### CustomerBillingAddressInput

- `line1` (string, optional)
- `line2` (string, optional)
- `city` (string, optional)
- `state` (string, optional)
- `zipCode` (string, optional)
- `country` (string, optional)

### ProvisionOrderLine

- `product` (ProvisionProduct, required)
- `startDate` (datetime, required)
- `externalId` (string, required)
- `name` (string, optional)
- `description` (string, optional)
- `endDate` (datetime, optional)
- `attributes` (list of ProvisionOrderLineAttribute, optional) — If not provided, pricing is pulled from the provisioned product attributes.
- `lineType` (enum, optional) — Defaults to `STANDARD`. Set to `CREDIT` for a discount or credit line: send its prices as positive amounts, and Paid subtracts them from the invoice.
  - Allowed values: `STANDARD`, `CREDIT`

### ProvisionBillingFrequencyOverride

- `frequency` (enum, required)
  - Allowed values: `monthly`, `quarterly`, `semiAnnually`, `annual`, `custom`
- `customMonths` (integer, optional, nullable)

### ContactBillingAddress

- `street` (string, optional)
- `city` (string, optional)
- `state` (string, optional)
- `country` (string, optional)
- `zipCode` (string, optional)

### ProvisionCreatedOrderLine

- `id` (string, required)
- `externalId` (string, required)
- `provisionStatus` (enum, required) — created: the entity was created; updated: the entity was updated
  - Allowed values: `created`, `updated`
- `createdAt` (datetime, required)
- `lineType` (enum, required)
  - Allowed values: `STANDARD`, `PRORATION_CREDIT`, `PRORATION_CHARGE`, `CREDIT`

### ProvisionProduct

- `name` (string, required)
- `externalId` (string, required)
- `productCode` (string, optional)
- `description` (string, optional)
- `attributes` (list of ProvisionProductAttributesItems, optional) — Product attributes to create or update on the provisioned product. These are upserted by name. If pricing.pricePoints.currency is omitted, the request order currency is used.

### ProvisionOrderLineAttribute

- `name` (string, required)
- `attributeId` (string, optional) — The existing product attribute's ID. Disambiguates catalogue fees with the same name; must belong to this line's product.
- `priceSource` (enum, optional) — Whether the line uses the catalog price or an intentional custom override. Omitted pricing uses the catalog; explicit pricing defaults to custom.
  - Allowed values: `catalog`, `custom`
- `quantity` (integer, optional)
- `pricing` (ProvisionOrderLineAttributePricing, optional) — When omitted, the line uses the pricing of the product attribute with the same name, unchanged. This includes pricing models that this request cannot express. Send pricing only to override the catalog price for this order.
- `creditAmount` (double, optional, nullable) — Overrides the credit amount on every credit benefit this attribute carries onto the order line. Paid grants creditAmount × quantity per allocation. When omitted, the product attribute's configured benefit amount applies. Send this or `creditAmountDecimal`; when both are sent they must be equal.
- `creditAmountDecimal` (string, optional, nullable) — The same amount as `creditAmount`, as an exact decimal string with up to 15 decimal places. Send this or `creditAmount`; when both are sent they must be equal.
- `overageUnitPrice` (integer, optional, nullable) — Overrides the overage unit price, in the currency's minor units, for credits consumed beyond the granted balance, on this attribute only: applied to every credit benefit this attribute carries onto the order line, or to the attribute's pricing when it carries no benefits, and it replaces this attribute's per-currency price for the order currency, so it is what this attribute bills in every currency. Other attributes on the order that price the same credits currency keep their own overage prices, and the invoice bills the highest entry for its currency across all of them. When omitted, the product attribute's configured overage applies; null clears it, so the attribute takes its order-currency per-currency price, or none if it has no map.
- `overageUnitPricesDecimal` (map from string to string, optional, nullable) — Exact overage price per credit, keyed by currency, as decimal text in the currency’s smallest stored unit. Used instead of overageUnitPrices when present. Requires decimal pricing to be enabled.
- `overageUnitPrices` (map from string to integer, optional, nullable) — Overrides this attribute's per-currency overage prices, in each currency's minor units keyed by uppercase ISO 4217 currency code, wherever overageUnitPrice would land. An entry for the order currency also becomes the attribute's overageUnitPrice. Keys must be currencies the product is priced in. When omitted, the product attribute's configured per-currency prices apply; null removes them, leaving only the scalar overage.
- `discountType` (enum, optional)
  - Allowed values: `percentage`, `fixed`
- `discountPercent` (double, optional) — Percentage discount, greater than 0 and at most 100, with at most 2 decimal places. Required when `discountType` is `percentage`.
- `discountAmount` (integer, optional) — Fixed discount in minor currency units (cents). Required when `discountType` is `fixed`.

### ProvisionProductAttributesItems

- `name` (string, required)
- `pricing` (ProvisionProductAttributesItemsPricing, required)
- `description` (string, optional)
- `active` (boolean, optional)
- `sequence` (integer, optional)
- `timeEstimateMinutes` (integer, optional)
- `creditBenefits` (list of ProvisionCreditBenefit, optional) — Credit benefits granted by this product attribute. These flow to every order line that selects this attribute.

### ProvisionOrderLineAttributePricing

When omitted, the line uses the pricing of the product attribute with the same name, unchanged. This includes pricing models that this request cannot express. Send pricing only to override the catalog price for this order.

- `chargeType` (enum, required)
  - Allowed values: `usage`, `recurring`, `oneTime`, `seatBased`
- `pricePoints` (ProvisionOrderLineAttributePricingPricePoints, required)
- `pricingModel` (enum, required)
  - Allowed values: `perUnit`, `volumePricing`, `graduatedPricing`
- `eventName` (string, optional)
- `billingFrequency` (enum, optional)
  - Allowed values: `monthly`, `quarterly`, `semiAnnually`, `annual`, `custom`
- `billingFrequencyCustomMonths` (integer, optional)
- `billingType` (enum, optional) — When the charge is billed. Usage charges must use arrears.
  - Allowed values: `advance`, `arrears`

### ProvisionProductAttributesItemsPricing

- `chargeType` (enum, required)
  - Allowed values: `usage`, `recurring`, `oneTime`, `seatBased`
- `pricePoints` (ProvisionProductAttributesItemsPricingPricePoints, required)
- `pricingModel` (enum, required)
  - Allowed values: `perUnit`, `volumePricing`, `graduatedPricing`
- `eventName` (string, optional)
- `billingFrequency` (enum, optional)
  - Allowed values: `monthly`, `quarterly`, `semiAnnually`, `annual`, `custom`
- `billingFrequencyCustomMonths` (integer, optional)
- `billingType` (enum, optional) — When the charge is billed. Usage charges must use arrears.
  - Allowed values: `advance`, `arrears`

### ProvisionCreditBenefit

- `creditsCurrencyKey` (string, required) — The `key` of the credits currency.
- `amount` (double, optional) — Credits granted per allocation period. Must be greater than 0. For an unlimited grant, set `isInfiniteTotal: true` and send any positive amount. Up to 15 decimal places. Send this or `amountDecimal`; when both are sent they must be equal.
- `amountDecimal` (string, optional) — The same amount as `amount`, as an exact decimal string with up to 15 decimal places. Send this or `amount`; when both are sent they must be equal. Must be greater than 0.
- `recipient` (enum, optional, default: organization)
  - Allowed values: `organization`, `seat`
- `isInfiniteTotal` (boolean, optional, default: false)
- `allocationCadence` (enum, optional, default: upfront)
  - Allowed values: `upfront`, `monthly`, `quarterly`, `semi_annually`
- `creditGrantTiming` (enum, optional)
  - Allowed values: `on_order_activation`, `on_payment`, `on_invoice_posted`
- `overageUnitPrice` (integer, optional, nullable)
- `overageUnitPricesDecimal` (map from string to string, optional, nullable) — Exact overage price per credit, keyed by currency, as decimal text in the currency’s smallest stored unit. Used instead of overageUnitPrices when present. Requires decimal pricing to be enabled.
- `overageUnitPrices` (map from string to integer, optional, nullable) — Overage price per credit in the currency's minor units (40 is $0.40 for USD, ¥40 for JPY, 0.040 KWD for KWD), keyed by uppercase ISO 4217 currency code. On an invoice, an entry for the invoice currency on any of the order's pricing or credit benefits beats every overageUnitPrice; overageUnitPrice applies only when no holder has an entry for that currency. Writes keep the two consistent for the primary currency (the organization's default when the product is priced in it, else the product's only pricing currency; an order line's own currency): a map entry for it sets overageUnitPrice, winning when a write sends both, and an overageUnitPrice sent without the map updates an existing entry for it. A write that sends only overageUnitPrice never creates a map.
- `rolloverAmount` (double, optional, nullable) — Up to 15 decimal places. Send this or `rolloverAmountDecimal`; when both are sent they must be equal.
- `rolloverAmountDecimal` (string, optional, nullable) — The same amount as `rolloverAmount`, as an exact decimal string with up to 15 decimal places. Send this or `rolloverAmount`; when both are sent they must be equal.
- `rolloverDuration` (integer, optional, nullable)
- `rolloverDurationUnit` (enum, optional)
  - Allowed values: `days`, `months`
- `createUsageLine` (boolean, optional, default: false) — When true, Paid adds a usage line to the order that draws down this credit currency: one credit for each signal whose event name is the `creditsCurrencyKey`. The line uses a product named `Paid Usage - <creditsCurrencyKey>`, with external ID `paid:usage:<creditsCurrencyKey>`, which Paid creates if it does not exist. An order gets one such line per credit currency, even when several benefits set this flag.

### ProvisionOrderLineAttributePricingPricePoints

- `unitPrice` (integer, required) — Price per unit, as a whole number in minor currency units (cents): 4900 is $49.00. Must be 0 or more. For a discount or credit, send a positive price on a line with `lineType: CREDIT`.
- `currency` (string, optional)
- `tiers` (list of ProvisionOrderLineAttributePricingPricePointsTiersItems, optional) — Optional pricing tiers for volume/graduated pricing models. When provided, overrides the default flat unitPrice structure.

### ProvisionProductAttributesItemsPricingPricePoints

- `unitPrice` (integer, required) — Price per unit, as a whole number in minor currency units (cents): 4900 is $49.00. Must be 0 or more. For a discount or credit, send a positive price on a line with `lineType: CREDIT`.
- `currency` (string, optional)
- `tiers` (list of ProvisionProductAttributesItemsPricingPricePointsTiersItems, optional) — Optional pricing tiers for volume/graduated pricing models. When provided, overrides the default flat unitPrice structure.

### ProvisionOrderLineAttributePricingPricePointsTiersItems

- `lowerBound` (integer, required)
- `flatAmount` (integer, optional) — Flat fee for this tier, in minor currency units (cents). Must be 0 or more.
- `index` (double, optional)
- `number` (integer, optional)
- `tierBillingType` (enum, optional)
  - Allowed values: `flat`, `perUnit`
- `unitAmount` (integer, optional) — Price per unit in this tier, in minor currency units (cents). Must be 0 or more.
- `upperBound` (integer, optional)

### ProvisionProductAttributesItemsPricingPricePointsTiersItems

- `lowerBound` (integer, required)
- `flatAmount` (integer, optional) — Flat fee for this tier, in minor currency units (cents). Must be 0 or more.
- `index` (double, optional)
- `number` (integer, optional)
- `tierBillingType` (enum, optional)
  - Allowed values: `flat`, `perUnit`
- `unitAmount` (integer, optional) — Price per unit in this tier, in minor currency units (cents). Must be 0 or more.
- `upperBound` (integer, optional)

## Examples

**Request**

```json
{
  "externalReference": {
    "source": "standard",
    "metadata": {
      "crmAccountId": "acct_4410",
      "crmDealId": "deal_88213"
    }
  },
  "customer": {
    "name": "Northwind Logistics",
    "externalId": "acct_4410",
    "email": "billing@northwind.example",
    "billingAddress": {
      "line1": "200 Harbor Way",
      "city": "Seattle",
      "state": "WA",
      "zipCode": "98101",
      "country": "US"
    }
  },
  "order": {
    "currency": "USD",
    "startDate": "2026-10-01T00:00:00.000Z",
    "externalId": "deal_88213",
    "lines": [
      {
        "product": {
          "name": "Growth plan",
          "externalId": "growth_plan",
          "attributes": [
            {
              "name": "Platform fee",
              "pricing": {
                "chargeType": "recurring",
                "pricePoints": {
                  "unitPrice": 49900,
                  "currency": "USD"
                },
                "pricingModel": "perUnit",
                "billingFrequency": "monthly",
                "billingType": "advance"
              }
            }
          ]
        },
        "startDate": "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": {
                  "unitPrice": 10000,
                  "currency": "USD"
                },
                "pricingModel": "perUnit",
                "billingFrequency": "monthly",
                "billingType": "advance"
              }
            }
          ]
        },
        "startDate": "2026-10-01T00:00:00.000Z",
        "externalId": "deal_88213_launch_discount",
        "endDate": "2027-01-01T00:00:00.000Z",
        "lineType": "CREDIT"
      }
    ],
    "name": "Northwind Logistics - Growth plan"
  }
}
```

**Response**

```json
{
  "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"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.agentpaid.io/api/v2/provision/"

payload = {
    "externalReference": {
        "source": "standard",
        "metadata": {
            "crmAccountId": "acct_4410",
            "crmDealId": "deal_88213"
        }
    },
    "customer": {
        "name": "Northwind Logistics",
        "externalId": "acct_4410",
        "email": "billing@northwind.example",
        "billingAddress": {
            "line1": "200 Harbor Way",
            "city": "Seattle",
            "state": "WA",
            "zipCode": "98101",
            "country": "US"
        }
    },
    "order": {
        "currency": "USD",
        "startDate": "2026-10-01T00:00:00.000Z",
        "externalId": "deal_88213",
        "lines": [
            {
                "product": {
                    "name": "Growth plan",
                    "externalId": "growth_plan",
                    "attributes": [
                        {
                            "name": "Platform fee",
                            "pricing": {
                                "chargeType": "recurring",
                                "pricePoints": {
                                    "unitPrice": 49900,
                                    "currency": "USD"
                                },
                                "pricingModel": "perUnit",
                                "billingFrequency": "monthly",
                                "billingType": "advance"
                            }
                        }
                    ]
                },
                "startDate": "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": {
                                    "unitPrice": 10000,
                                    "currency": "USD"
                                },
                                "pricingModel": "perUnit",
                                "billingFrequency": "monthly",
                                "billingType": "advance"
                            }
                        }
                    ]
                },
                "startDate": "2026-10-01T00:00:00.000Z",
                "externalId": "deal_88213_launch_discount",
                "endDate": "2027-01-01T00:00:00.000Z",
                "lineType": "CREDIT"
            }
        ],
        "name": "Northwind Logistics - Growth plan"
    }
}
headers = {
    "idempotency-key": "deal_88213-2026-09-30T14:05:00Z",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.agentpaid.io/api/v2/provision/';
const options = {
  method: 'POST',
  headers: {
    'idempotency-key': 'deal_88213-2026-09-30T14:05:00Z',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"externalReference":{"source":"standard","metadata":{"crmAccountId":"acct_4410","crmDealId":"deal_88213"}},"customer":{"name":"Northwind Logistics","externalId":"acct_4410","email":"billing@northwind.example","billingAddress":{"line1":"200 Harbor Way","city":"Seattle","state":"WA","zipCode":"98101","country":"US"}},"order":{"currency":"USD","startDate":"2026-10-01T00:00:00.000Z","externalId":"deal_88213","lines":[{"product":{"name":"Growth plan","externalId":"growth_plan","attributes":[{"name":"Platform fee","pricing":{"chargeType":"recurring","pricePoints":{"unitPrice":49900,"currency":"USD"},"pricingModel":"perUnit","billingFrequency":"monthly","billingType":"advance"}}]},"startDate":"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":{"unitPrice":10000,"currency":"USD"},"pricingModel":"perUnit","billingFrequency":"monthly","billingType":"advance"}}]},"startDate":"2026-10-01T00:00:00.000Z","externalId":"deal_88213_launch_discount","endDate":"2027-01-01T00:00:00.000Z","lineType":"CREDIT"}],"name":"Northwind Logistics - Growth plan"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentpaid.io/api/v2/provision/"

	payload := strings.NewReader("{\n  \"externalReference\": {\n    \"source\": \"standard\",\n    \"metadata\": {\n      \"crmAccountId\": \"acct_4410\",\n      \"crmDealId\": \"deal_88213\"\n    }\n  },\n  \"customer\": {\n    \"name\": \"Northwind Logistics\",\n    \"externalId\": \"acct_4410\",\n    \"email\": \"billing@northwind.example\",\n    \"billingAddress\": {\n      \"line1\": \"200 Harbor Way\",\n      \"city\": \"Seattle\",\n      \"state\": \"WA\",\n      \"zipCode\": \"98101\",\n      \"country\": \"US\"\n    }\n  },\n  \"order\": {\n    \"currency\": \"USD\",\n    \"startDate\": \"2026-10-01T00:00:00.000Z\",\n    \"externalId\": \"deal_88213\",\n    \"lines\": [\n      {\n        \"product\": {\n          \"name\": \"Growth plan\",\n          \"externalId\": \"growth_plan\",\n          \"attributes\": [\n            {\n              \"name\": \"Platform fee\",\n              \"pricing\": {\n                \"chargeType\": \"recurring\",\n                \"pricePoints\": {\n                  \"unitPrice\": 49900,\n                  \"currency\": \"USD\"\n                },\n                \"pricingModel\": \"perUnit\",\n                \"billingFrequency\": \"monthly\",\n                \"billingType\": \"advance\"\n              }\n            }\n          ]\n        },\n        \"startDate\": \"2026-10-01T00:00:00.000Z\",\n        \"externalId\": \"deal_88213_platform\"\n      },\n      {\n        \"product\": {\n          \"name\": \"Launch discount\",\n          \"externalId\": \"launch_discount\",\n          \"attributes\": [\n            {\n              \"name\": \"Launch discount\",\n              \"pricing\": {\n                \"chargeType\": \"recurring\",\n                \"pricePoints\": {\n                  \"unitPrice\": 10000,\n                  \"currency\": \"USD\"\n                },\n                \"pricingModel\": \"perUnit\",\n                \"billingFrequency\": \"monthly\",\n                \"billingType\": \"advance\"\n              }\n            }\n          ]\n        },\n        \"startDate\": \"2026-10-01T00:00:00.000Z\",\n        \"externalId\": \"deal_88213_launch_discount\",\n        \"endDate\": \"2027-01-01T00:00:00.000Z\",\n        \"lineType\": \"CREDIT\"\n      }\n    ],\n    \"name\": \"Northwind Logistics - Growth plan\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("idempotency-key", "deal_88213-2026-09-30T14:05:00Z")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.agentpaid.io/api/v2/provision/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["idempotency-key"] = 'deal_88213-2026-09-30T14:05:00Z'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"externalReference\": {\n    \"source\": \"standard\",\n    \"metadata\": {\n      \"crmAccountId\": \"acct_4410\",\n      \"crmDealId\": \"deal_88213\"\n    }\n  },\n  \"customer\": {\n    \"name\": \"Northwind Logistics\",\n    \"externalId\": \"acct_4410\",\n    \"email\": \"billing@northwind.example\",\n    \"billingAddress\": {\n      \"line1\": \"200 Harbor Way\",\n      \"city\": \"Seattle\",\n      \"state\": \"WA\",\n      \"zipCode\": \"98101\",\n      \"country\": \"US\"\n    }\n  },\n  \"order\": {\n    \"currency\": \"USD\",\n    \"startDate\": \"2026-10-01T00:00:00.000Z\",\n    \"externalId\": \"deal_88213\",\n    \"lines\": [\n      {\n        \"product\": {\n          \"name\": \"Growth plan\",\n          \"externalId\": \"growth_plan\",\n          \"attributes\": [\n            {\n              \"name\": \"Platform fee\",\n              \"pricing\": {\n                \"chargeType\": \"recurring\",\n                \"pricePoints\": {\n                  \"unitPrice\": 49900,\n                  \"currency\": \"USD\"\n                },\n                \"pricingModel\": \"perUnit\",\n                \"billingFrequency\": \"monthly\",\n                \"billingType\": \"advance\"\n              }\n            }\n          ]\n        },\n        \"startDate\": \"2026-10-01T00:00:00.000Z\",\n        \"externalId\": \"deal_88213_platform\"\n      },\n      {\n        \"product\": {\n          \"name\": \"Launch discount\",\n          \"externalId\": \"launch_discount\",\n          \"attributes\": [\n            {\n              \"name\": \"Launch discount\",\n              \"pricing\": {\n                \"chargeType\": \"recurring\",\n                \"pricePoints\": {\n                  \"unitPrice\": 10000,\n                  \"currency\": \"USD\"\n                },\n                \"pricingModel\": \"perUnit\",\n                \"billingFrequency\": \"monthly\",\n                \"billingType\": \"advance\"\n              }\n            }\n          ]\n        },\n        \"startDate\": \"2026-10-01T00:00:00.000Z\",\n        \"externalId\": \"deal_88213_launch_discount\",\n        \"endDate\": \"2027-01-01T00:00:00.000Z\",\n        \"lineType\": \"CREDIT\"\n      }\n    ],\n    \"name\": \"Northwind Logistics - Growth plan\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.agentpaid.io/api/v2/provision/")
  .header("idempotency-key", "deal_88213-2026-09-30T14:05:00Z")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"externalReference\": {\n    \"source\": \"standard\",\n    \"metadata\": {\n      \"crmAccountId\": \"acct_4410\",\n      \"crmDealId\": \"deal_88213\"\n    }\n  },\n  \"customer\": {\n    \"name\": \"Northwind Logistics\",\n    \"externalId\": \"acct_4410\",\n    \"email\": \"billing@northwind.example\",\n    \"billingAddress\": {\n      \"line1\": \"200 Harbor Way\",\n      \"city\": \"Seattle\",\n      \"state\": \"WA\",\n      \"zipCode\": \"98101\",\n      \"country\": \"US\"\n    }\n  },\n  \"order\": {\n    \"currency\": \"USD\",\n    \"startDate\": \"2026-10-01T00:00:00.000Z\",\n    \"externalId\": \"deal_88213\",\n    \"lines\": [\n      {\n        \"product\": {\n          \"name\": \"Growth plan\",\n          \"externalId\": \"growth_plan\",\n          \"attributes\": [\n            {\n              \"name\": \"Platform fee\",\n              \"pricing\": {\n                \"chargeType\": \"recurring\",\n                \"pricePoints\": {\n                  \"unitPrice\": 49900,\n                  \"currency\": \"USD\"\n                },\n                \"pricingModel\": \"perUnit\",\n                \"billingFrequency\": \"monthly\",\n                \"billingType\": \"advance\"\n              }\n            }\n          ]\n        },\n        \"startDate\": \"2026-10-01T00:00:00.000Z\",\n        \"externalId\": \"deal_88213_platform\"\n      },\n      {\n        \"product\": {\n          \"name\": \"Launch discount\",\n          \"externalId\": \"launch_discount\",\n          \"attributes\": [\n            {\n              \"name\": \"Launch discount\",\n              \"pricing\": {\n                \"chargeType\": \"recurring\",\n                \"pricePoints\": {\n                  \"unitPrice\": 10000,\n                  \"currency\": \"USD\"\n                },\n                \"pricingModel\": \"perUnit\",\n                \"billingFrequency\": \"monthly\",\n                \"billingType\": \"advance\"\n              }\n            }\n          ]\n        },\n        \"startDate\": \"2026-10-01T00:00:00.000Z\",\n        \"externalId\": \"deal_88213_launch_discount\",\n        \"endDate\": \"2027-01-01T00:00:00.000Z\",\n        \"lineType\": \"CREDIT\"\n      }\n    ],\n    \"name\": \"Northwind Logistics - Growth plan\"\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.agentpaid.io/api/v2/provision/', [
  'body' => '{
  "externalReference": {
    "source": "standard",
    "metadata": {
      "crmAccountId": "acct_4410",
      "crmDealId": "deal_88213"
    }
  },
  "customer": {
    "name": "Northwind Logistics",
    "externalId": "acct_4410",
    "email": "billing@northwind.example",
    "billingAddress": {
      "line1": "200 Harbor Way",
      "city": "Seattle",
      "state": "WA",
      "zipCode": "98101",
      "country": "US"
    }
  },
  "order": {
    "currency": "USD",
    "startDate": "2026-10-01T00:00:00.000Z",
    "externalId": "deal_88213",
    "lines": [
      {
        "product": {
          "name": "Growth plan",
          "externalId": "growth_plan",
          "attributes": [
            {
              "name": "Platform fee",
              "pricing": {
                "chargeType": "recurring",
                "pricePoints": {
                  "unitPrice": 49900,
                  "currency": "USD"
                },
                "pricingModel": "perUnit",
                "billingFrequency": "monthly",
                "billingType": "advance"
              }
            }
          ]
        },
        "startDate": "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": {
                  "unitPrice": 10000,
                  "currency": "USD"
                },
                "pricingModel": "perUnit",
                "billingFrequency": "monthly",
                "billingType": "advance"
              }
            }
          ]
        },
        "startDate": "2026-10-01T00:00:00.000Z",
        "externalId": "deal_88213_launch_discount",
        "endDate": "2027-01-01T00:00:00.000Z",
        "lineType": "CREDIT"
      }
    ],
    "name": "Northwind Logistics - Growth plan"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'idempotency-key' => 'deal_88213-2026-09-30T14:05:00Z',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.agentpaid.io/api/v2/provision/");
var request = new RestRequest(Method.POST);
request.AddHeader("idempotency-key", "deal_88213-2026-09-30T14:05:00Z");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"externalReference\": {\n    \"source\": \"standard\",\n    \"metadata\": {\n      \"crmAccountId\": \"acct_4410\",\n      \"crmDealId\": \"deal_88213\"\n    }\n  },\n  \"customer\": {\n    \"name\": \"Northwind Logistics\",\n    \"externalId\": \"acct_4410\",\n    \"email\": \"billing@northwind.example\",\n    \"billingAddress\": {\n      \"line1\": \"200 Harbor Way\",\n      \"city\": \"Seattle\",\n      \"state\": \"WA\",\n      \"zipCode\": \"98101\",\n      \"country\": \"US\"\n    }\n  },\n  \"order\": {\n    \"currency\": \"USD\",\n    \"startDate\": \"2026-10-01T00:00:00.000Z\",\n    \"externalId\": \"deal_88213\",\n    \"lines\": [\n      {\n        \"product\": {\n          \"name\": \"Growth plan\",\n          \"externalId\": \"growth_plan\",\n          \"attributes\": [\n            {\n              \"name\": \"Platform fee\",\n              \"pricing\": {\n                \"chargeType\": \"recurring\",\n                \"pricePoints\": {\n                  \"unitPrice\": 49900,\n                  \"currency\": \"USD\"\n                },\n                \"pricingModel\": \"perUnit\",\n                \"billingFrequency\": \"monthly\",\n                \"billingType\": \"advance\"\n              }\n            }\n          ]\n        },\n        \"startDate\": \"2026-10-01T00:00:00.000Z\",\n        \"externalId\": \"deal_88213_platform\"\n      },\n      {\n        \"product\": {\n          \"name\": \"Launch discount\",\n          \"externalId\": \"launch_discount\",\n          \"attributes\": [\n            {\n              \"name\": \"Launch discount\",\n              \"pricing\": {\n                \"chargeType\": \"recurring\",\n                \"pricePoints\": {\n                  \"unitPrice\": 10000,\n                  \"currency\": \"USD\"\n                },\n                \"pricingModel\": \"perUnit\",\n                \"billingFrequency\": \"monthly\",\n                \"billingType\": \"advance\"\n              }\n            }\n          ]\n        },\n        \"startDate\": \"2026-10-01T00:00:00.000Z\",\n        \"externalId\": \"deal_88213_launch_discount\",\n        \"endDate\": \"2027-01-01T00:00:00.000Z\",\n        \"lineType\": \"CREDIT\"\n      }\n    ],\n    \"name\": \"Northwind Logistics - Growth plan\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "idempotency-key": "deal_88213-2026-09-30T14:05:00Z",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "externalReference": [
    "source": "standard",
    "metadata": [
      "crmAccountId": "acct_4410",
      "crmDealId": "deal_88213"
    ]
  ],
  "customer": [
    "name": "Northwind Logistics",
    "externalId": "acct_4410",
    "email": "billing@northwind.example",
    "billingAddress": [
      "line1": "200 Harbor Way",
      "city": "Seattle",
      "state": "WA",
      "zipCode": "98101",
      "country": "US"
    ]
  ],
  "order": [
    "currency": "USD",
    "startDate": "2026-10-01T00:00:00.000Z",
    "externalId": "deal_88213",
    "lines": [
      [
        "product": [
          "name": "Growth plan",
          "externalId": "growth_plan",
          "attributes": [
            [
              "name": "Platform fee",
              "pricing": [
                "chargeType": "recurring",
                "pricePoints": [
                  "unitPrice": 49900,
                  "currency": "USD"
                ],
                "pricingModel": "perUnit",
                "billingFrequency": "monthly",
                "billingType": "advance"
              ]
            ]
          ]
        ],
        "startDate": "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": [
                  "unitPrice": 10000,
                  "currency": "USD"
                ],
                "pricingModel": "perUnit",
                "billingFrequency": "monthly",
                "billingType": "advance"
              ]
            ]
          ]
        ],
        "startDate": "2026-10-01T00:00:00.000Z",
        "externalId": "deal_88213_launch_discount",
        "endDate": "2027-01-01T00:00:00.000Z",
        "lineType": "CREDIT"
      ]
    ],
    "name": "Northwind Logistics - Growth plan"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentpaid.io/api/v2/provision/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```