---
#### Embedded integrators
`embedded` and `embedded+` are modular. You select the parts of Seamless OS that you use.
##### Available modules
- **Connectivity** — Subscription management: create, update, delete, upgrade, downgrade, topup, addon, and port-in.
- **User management** — User management: create, update, and delete.
- **Payments** — Our payment APIs take billing and payments off your side.
- **Order management** — Manage customer orders and fulfillment.
- **Product management** — Configure your products and your offers with our product catalog APIs.
##### Example setups
**Connectivity and product management only**
**Connectivity, product management, and payments**
**Connectivity, product management, and order management**
#### Embedded+ integrators
`embedded+` gives you the most control. You own the whole customer journey, and you select the
parts that we run for you.
This is the **mix-and-match integration**. Select connectivity, payments, order management,
product management, or any combination of them.
#### Next steps
- [Get started](/api-reference/get-started.md) — Place your first order with the Seamless OS API.
## Guides
### Place an order
Canonical URL: https://docs.valdyr.tech/developer-guide/use-cases/place-an-order
Orders are the API's shopping cart. You create a draft order, configure it step by step with line items and customer details, price it, and submit it for fulfillment. Until submission, everything is editable — nothing is provisioned and nothing is charged.
This guide takes you through one complete integration. A US consumer, Jane Smith, orders a new
mobile subscription with a new phone number. The subscription is delivered as an eSIM to her
iPhone.
On the way, the guide covers every decision that you meet. An existing customer or a new one.
The pre-order validation tools. The price calculation, the submission requirements, and
cancellation.
#### Prerequisites
You need all of these before you start:
- **API credentials**: Every request carries both an `Authorization: Bearer` access token and an `X-API-Key` header
- **Product offerings**: At least one `AVAILABLE` product offering to sell — see [Product Management](/developer-guide/use-cases/product-management.md)
- **Payment integration**: If your orders require payment, a way to run payment sessions — see [Payment Processing](/developer-guide/use-cases/payment-processing.md)
#### Overview
**1. Choose a product offering**
List product offerings and pick the plan the customer is buying.
**2. Verify customer input with the order tools**
Validate the address, read the network coverage, and make sure that the device supports an eSIM.
Do all three before you build the order.
**3. Create a draft order**
Start an order for an existing customer or create the customer together with the order.
**4. Add a subscription line item**
Attach the product offering, subscriber details, and SIM configuration.
**5. Review the validation state**
Fetch the order and resolve any missing fields or validation errors.
**6. Read the price**
Read the exact total, including jurisdiction-level US taxes, before asking the customer to pay.
**7. Meet the requirements and submit**
Complete payment, payment profile, or signing requirements, then submit the order.
**8. Track the order to completion**
Watch the order state until the subscription is created and activated.
#### The order lifecycle
An order's `state` tells you exactly what you can do with it:
| State | Meaning |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| `PENDING` | Draft (cart) state. The order can be modified, priced, and submitted. |
| `PENDING_PAYMENT` | The order is locked and awaiting payment completion. |
| `SUBMITTED` | You submitted the order for processing. |
| `PENDING_APPROVAL` | The order needs admin or manager approval through `POST /orders/{orderId}/approve` before it continues. |
| `PROCESSING` | The order is in fulfillment. |
| `COMPLETED` | The order was successfully fulfilled. |
| `CANCELLED` | The order was canceled before completion. |
| `EXPIRED` | The order expired due to inactivity. |
| `FAILED` | Order fulfillment failed. |
> **Note**
>
> A draft order expires. Every order carries an `expiresAt` timestamp, and each update moves it
> forward. A cart that nobody touches goes to `EXPIRED`.
#### Step-by-step implementation
> **Info**
>
> Example responses in this guide are trimmed to the fields relevant to each step. The API always
> returns the complete object.
##### Step 1: Choose a product offering
List the product offerings available to your customer type. The `productOfferingId` you pick here is what you attach to the order's line item. Filter by `types=SUBSCRIPTION` to only see plans that create a mobile subscription.
```bash
curl -X GET "{BASE_URL}/product-offerings?customerType=CONSUMER&types=SUBSCRIPTION" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY"
```
Jane picks the 10 GB plan:
```json
{
"items": [
{
"productOfferingId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
"status": "AVAILABLE",
"name": "Seamless 10GB",
"description": "10GB of high-speed data with unlimited calls and texts",
"customerType": "CONSUMER",
"product": {
"productId": "9b2f80c4-6a1d-4e3b-8c5f-7d9e0a1b2c3d",
"internalName": "seamless_cell_10gb_us",
"type": "SUBSCRIPTION",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"networkProviderId": "tmobile-us",
"features": {
"dataMb": 10240,
"includedCallSeconds": 3600,
"includedSms": 500
}
},
"price": {
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "RECURRING",
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"standardDiscount": { "amountMinor": 500 },
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 12
},
"discount": {
"amountMinor": 200
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 300,
"duration": { "unit": "MONTHS", "value": 3 }
}
},
"currencyOptionsMinor": {
"USD": 2999,
"SEK": 29900
}
}
}
],
"pagination": {
"nextCursor": null
}
}
```
##### Step 2: Verify customer input with the order tools
With the order tools you validate customer input at form time, before it becomes a validation error on the order. All four are stateless `POST` endpoints — call them as often as you like.
###### Validate the service address
In the US, the subscriber's address doubles as the E911 emergency address, so it must be precise. Validate it as soon as the customer types it.
```bash
curl -X POST "{BASE_URL}/tools/validate-address" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"address": {
"street1": "826 Valencia St",
"city": "San Francisco",
"state": "CA",
"zip": "94110",
"country": "US"
}
}'
```
```json
{
"valid": true
}
```
> **Note**
>
> A response can carry a `suggestedAddress` for a valid input, when the network registry holds a
> more exact form of the address. Take that form. The formatting of the network prevents a
> provisioning fault later.
###### Check network coverage
Make sure that the customer gets service at their address. Show them the quality to expect on each technology.
```bash
curl -X POST "{BASE_URL}/tools/check-network-coverage" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"address": {
"street1": "826 Valencia St",
"city": "San Francisco",
"state": "CA",
"zip": "94110",
"country": "US"
}
}'
```
The `coverageLevel` is one of `EXCELLENT`, `GOOD`, `FAIR`, `POOR`, or `NO_COVERAGE`:
```json
{
"address": {
"street1": "826 Valencia St",
"city": "San Francisco",
"state": "CA",
"zip": "94110",
"country": "US"
},
"coverageLevel": "EXCELLENT",
"networkProviderId": "tmobile-us"
}
```
###### Check device eSIM support
Jane wants an eSIM, so look up the IMEI of her phone. The response says whether the device supports an eSIM. Some networks also need the IMEI later, to activate the eSIM, so collect it now.
```bash
curl -X POST "{BASE_URL}/tools/get-device-info" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"imei": "356938035643809"
}'
```
```json
{
"imei": "356938035643809",
"tac": "35693803",
"esim": true,
"manufacturer": "Apple",
"model": "A2653",
"marketingName": "iPhone 15 Pro"
}
```
###### Check porting eligibility (port-ins only)
Jane takes a new number, so this step does not apply to her. If your customer wants to bring
their own number, make sure that the number is portable before you collect the porting
details.
```bash
curl -X POST "{BASE_URL}/tools/check-porting-eligibility" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"msisdn": "+14155550188"
}'
```
```json
{
"msisdn": "+14155550188",
"eligible": true,
"networkProviderId": "att-us"
}
```
##### Step 3: Create a draft order
Every order needs a `customerType` (`CONSUMER` or `BUSINESS`). Everything else can be added later, but the `customer` field is where you make your first real decision:
- **Existing customer** — pass `"customer": { "customerId": "..." }`. The `customerId` accepts
the internal UUID and your own external reference ID. An external reference ID needs the
`rid_` prefix, as in `rid_crm-customer-12345`, so that the API can tell it from a UUID.
- **New customer** — pass the details of the customer. `name` and `customerType` are required.
The API creates the customer as part of order fulfillment. If you also pass a `referenceId`
that a customer already carries, the API takes that customer and creates no duplicate. You
can call this from a flow that does not know whether the customer exists.
The `user` field names the person who uses the services. It follows the same pattern. Pass
`userId` for a returning user, or `name` and `email` to create one.
Jane is new, so we create both the customer and the user with the order:
```bash
curl -X POST "{BASE_URL}/orders" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customerType": "CONSUMER",
"customer": {
"name": "Jane Smith",
"customerType": "CONSUMER",
"referenceId": "crm-cust-84321",
"contact": {
"email": "jane.smith@example.com",
"msisdn": "+14155550123"
},
"billing": {
"method": "EMAIL_INVOICE",
"email": "jane.smith@example.com",
"currency": "USD",
"address": {
"street1": "826 Valencia St",
"city": "San Francisco",
"state": "CA",
"zip": "94110",
"country": "US"
}
}
},
"user": {
"name": "Jane Smith",
"email": "jane.smith@example.com",
"msisdn": "+14155550123"
},
"billing": {
"name": "Jane Smith",
"email": "jane.smith@example.com",
"address": {
"street1": "826 Valencia St",
"city": "San Francisco",
"state": "CA",
"zip": "94110",
"country": "US"
}
}
}'
```
The response is a draft order in `PENDING` state. Note `newCustomer: true` — the customer record itself is created during fulfillment, so it has no `customerId` yet:
```json
{
"orderId": "296af5b6-f3b3-4128-b307-5ddc9190502f",
"state": "PENDING",
"customer": {
"customerType": "CONSUMER",
"name": "Jane Smith",
"newCustomer": true
},
"user": {
"userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Jane Smith",
"newUser": true
},
"lineItems": [],
"validation": {
"isValid": false,
"missingFields": ["lineItems"]
},
"requirements": {
"requiresPayment": "REQUIRED",
"requiresPaymentProfile": "NOT_REQUIRED",
"requiresSigning": "NOT_REQUIRED"
},
"createdAt": "2026-07-12T17:00:00Z",
"updatedAt": "2026-07-12T17:00:00Z",
"expiresAt": "2026-07-19T17:00:00Z"
}
```
For an existing customer, the request collapses to:
```json
{
"customerType": "CONSUMER",
"customer": {
"customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479"
}
}
```
> **Note**
>
> You can also pass initial `lineItems` and a `promoCode` directly in the create request. This guide
> adds line items separately to show the progressive flow, but a single create call with everything
> inline is equally valid.
##### Step 4: Add a subscription line item
Add the plan to the order with `POST /orders/{orderId}/line-items`. A `SUBSCRIPTION` line item requires `type`, a `lineItemId` you choose (unique within the order), and the `productOfferingId`. The `subscriber` and `sim` objects are required eventually — provide them here or fill them in later with an update.
For the phone number, you have three options:
- **Leave `msisdn` empty** to have a number assigned automatically (what Jane does).
- **Pick a number from the number pool** and pass both the `msisdn` and the `leaseToken` you received when leasing it.
- **Port in an existing number** by setting the `msisdn`, `portingRequested: true`, and `porting.details`.
```bash
curl -X POST "{BASE_URL}/orders/296af5b6-f3b3-4128-b307-5ddc9190502f/line-items" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"lineItem": {
"type": "SUBSCRIPTION",
"lineItemId": "line-item-1",
"productOfferingId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
"subscriber": {
"name": "Jane Smith",
"email": "jane.smith@example.com",
"address": {
"street1": "826 Valencia St",
"city": "San Francisco",
"state": "CA",
"zip": "94110",
"country": "US"
}
},
"sim": {
"esim": true,
"imei": "356938035643809"
}
}
}'
```
The response echoes the line item:
```json
{
"type": "SUBSCRIPTION",
"lineItemId": "line-item-1",
"productOfferingId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
"subscriber": {
"name": "Jane Smith",
"email": "jane.smith@example.com",
"address": {
"street1": "826 Valencia St",
"city": "San Francisco",
"state": "CA",
"zip": "94110",
"country": "US"
}
},
"sim": {
"esim": true,
"imei": "356938035643809"
}
}
```
A line item for a port-in looks like this instead. US porting details require `firstName`,
`lastName`, and `address`. With `tempNumber: true` the customer gets a temporary number to use
until the port completes.
```json
{
"type": "SUBSCRIPTION",
"lineItemId": "line-item-1",
"productOfferingId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
"msisdn": "+14155550188",
"portingRequested": true,
"tempNumber": true,
"porting": {
"details": {
"firstName": "Jane",
"lastName": "Smith",
"accountNumber": "7724318842",
"passcode": "4821",
"address": {
"street1": "826 Valencia St",
"city": "San Francisco",
"state": "CA",
"zip": "94110",
"country": "US"
}
}
},
"subscriber": {
"name": "Jane Smith",
"email": "jane.smith@example.com"
},
"sim": {
"esim": true,
"imei": "356938035643809"
}
}
```
To change a line item while the order is still `PENDING`, use `PUT
/orders/{orderId}/line-items/{lineItemId}`. To remove one, use `DELETE
/orders/{orderId}/line-items/{lineItemId}`.
> **Warning**
>
> If the order carries anything to ship, add a `shipping` object with a recipient `name` and
> `address`. A physical SIM (`"esim": false`) and hardware both ship. Jane takes an eSIM, so this
> order needs no `shipping` object.
##### Step 5: Review the order's validation state
Line items are returned as part of the order, so `GET /orders/{orderId}` is your single read for everything: line items, validation, requirements, and pricing.
```bash
curl -X GET "{BASE_URL}/orders/296af5b6-f3b3-4128-b307-5ddc9190502f" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY"
```
Jane's order is now complete and ready to submit:
```json
{
"orderId": "296af5b6-f3b3-4128-b307-5ddc9190502f",
"state": "PENDING",
"customer": {
"customerType": "CONSUMER",
"name": "Jane Smith",
"newCustomer": true
},
"lineItems": [
{
"type": "SUBSCRIPTION",
"lineItemId": "line-item-1",
"productOfferingId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
"sim": {
"esim": true,
"imei": "356938035643809"
}
}
],
"validation": {
"isValid": true
},
"requirements": {
"requiresPayment": "REQUIRED",
"requiresPaymentProfile": "NOT_REQUIRED",
"requiresSigning": "NOT_REQUIRED"
},
"createdAt": "2026-07-12T17:00:00Z",
"updatedAt": "2026-07-12T17:04:00Z",
"expiresAt": "2026-07-19T17:04:00Z"
}
```
When something is missing, `validation` tells you exactly what, at both the order level and per line item:
```json
{
"isValid": false,
"missingFields": ["billing.address"],
"lineItemValidation": [
{
"lineItemId": "line-item-1",
"isValid": false,
"missingFields": ["subscriber.name", "sim.iccid"]
}
]
}
```
Fix missing fields with `PUT /orders/{orderId}` (order details) and `PUT /orders/{orderId}/line-items/{lineItemId}` (line item details), then re-fetch.
##### Step 6: Read the price
The platform calculates the price again each time the order changes, and returns it as `pricing`
on the order. Read the order to get the exact amount due before you collect the payment. On a US
order the tax is calculated per jurisdiction, from the addresses on the order. The address fields
in Step 5 must be correct before this number means anything.
```bash
curl "{BASE_URL}/orders/296af5b6-f3b3-4128-b307-5ddc9190502f" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY"
```
```json
{
"pricing": {
"subtotalMinor": 2999,
"taxAmountMinor": 450,
"totalMinor": 2749,
"taxIncluded": false,
"currency": "USD",
"recurringCosts": {
"subtotalMinor": 2299,
"totalMinor": 2299,
"taxIncluded": false,
"billingCycle": {
"period": "MONTHLY",
"interval": 1
}
},
"lineItems": [
{
"lineItemId": "line-item-1",
"description": "Seamless 10GB",
"subtotalMinor": 2999,
"discounts": [
{ "name": "Standard discount", "amountMinor": 500 },
{ "name": "12-month commitment", "amountMinor": 200 }
],
"totalDiscountsMinor": 700,
"taxAmountMinor": 450,
"taxIncluded": false,
"totalMinor": 2749,
"recurringAmountMinor": 2299
}
],
"calculatedAt": "2026-07-12T17:05:00Z"
}
}
```
This is where the discounts of the offering turn into money. The catalog listed Seamless 10GB
at `2999` in Step 1, and it still does. Here that `2999` is the `subtotalMinor`. The
`standardDiscount` and the `bindingContract.discount` of the offering come off as
`totalDiscountsMinor`. The platform calculates the tax on what is left, and `totalMinor` is the
amount to charge.
Three more discounts apply at this same point. A promo code on the order. A price list
assigned to the customer. A discount on the subscription.
> **Note**
>
> The platform cannot price an invalid order. If this operation returns an error, get the order and
> correct the `validation` problems first.
Amounts are integers in the minor units of `currency`, so `2749` is $27.49. The `subtotalMinor`
field gives the amount before discounts and tax. The platform reports the discounts of each line
item, so the total is `2999`, less the `700` of `totalDiscountsMinor`, plus the `450` of tax.
In the US, `recurringCosts` does not include `taxAmountMinor`. The platform calculates the tax on
a recurring charge when it makes the invoice. It does not estimate that tax here.
##### Step 7: Meet the submission requirements and submit
The `requirements` object of the order tells you what must happen before you submit it. Each
requirement is `NOT_REQUIRED`, `OPTIONAL`, or `REQUIRED`. What you get depends on the platform
configuration and on the contents of the order. A prepaid order of free items alone can need
nothing. A postpaid order normally requires a card capture or a signature.
| Requirement | When `REQUIRED` | Provide on submit |
| ------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `requiresPayment` | The order total must be paid before fulfillment | an `externalPayment` reference, or pay through a payment session — no submit call needed |
| `requiresPaymentProfile` | A stored payment method is needed for future billing | `paymentProfileSessionId` from a completed profile session |
| `requiresSigning` | The customer must digitally sign the order | `signingSessionId` from a completed signing session |
[Payment processing](/developer-guide/use-cases/payment-processing.md) covers how to create and
complete a payment session and a payment profile session. The [API reference](/api-reference.md)
documents a signing session.
An order that pays through a payment session or a payment link moves to `PENDING_PAYMENT`. The
platform submits it as soon as the payment succeeds. If the customer paid outside the platform,
pass an `externalPayment` object on submit, with a `reference` in it. The order then counts as
paid.
Jane's order has `requiresPayment: "REQUIRED"` and she pays through a hosted payment session, so there is no submit call to make. Once her payment succeeds, the platform submits the order — poll it until it leaves `PENDING_PAYMENT`:
```bash
curl "{BASE_URL}/orders/296af5b6-f3b3-4128-b307-5ddc9190502f" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY"
```
```json
{
"orderId": "296af5b6-f3b3-4128-b307-5ddc9190502f",
"state": "SUBMITTED",
"paymentSessionId": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
"submittedAt": "2026-07-12T17:08:00Z"
}
```
The submit endpoint accepts an order in the `PENDING` state only, and a payment can start on a
complete order only. A payment session and a payment link run the same validation as a submit,
so an order in `PENDING_PAYMENT` is known to be submittable already. Call submit yourself when
the requirements are met outside a payment session: an `externalPayment` reference, a payment
profile session, or a signing session.
##### Step 8: Track the order to completion
After the submit, the order moves through `SUBMITTED` → `PROCESSING` → `COMPLETED`. It can
also go to `PENDING_APPROVAL` or `FAILED` on the way. Poll `GET /orders/{orderId}` for the
state. To poll nothing, subscribe to the `order.statusChanged` webhook event.
```bash
curl -X GET "{BASE_URL}/orders/296af5b6-f3b3-4128-b307-5ddc9190502f" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY"
```
On completion, `createdEntities` maps each line item to what it produced — Jane's subscription, with her newly assigned number:
```json
{
"orderId": "296af5b6-f3b3-4128-b307-5ddc9190502f",
"state": "COMPLETED",
"customer": {
"customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
"customerType": "CONSUMER",
"name": "Jane Smith",
"newCustomer": true
},
"lineItems": [
{
"type": "SUBSCRIPTION",
"lineItemId": "line-item-1",
"productOfferingId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
}
],
"createdEntities": {
"subscriptions": [
{
"subscriptionId": "d5f7a2b1-3c4e-4f5a-8b9c-0d1e2f3a4b5c",
"status": "ACTIVATED",
"msisdn": "+14155550111",
"display": "(415) 555-0111",
"createdByLineItem": "line-item-1"
}
]
},
"submittedAt": "2026-07-12T17:08:00Z",
"completedAt": "2026-07-12T17:11:00Z"
}
```
> **Warning**
>
> Read `state` on the order before you tell the customer that the service is live. An order fulfills
> all its line items or none of them.
##### Canceling a draft order
If the customer abandons the purchase, cancel the order. The cancel releases the resources that
the order reserved. Only an order in the `PENDING` state can be canceled. The optional body
accepts `metadata` for your own bookkeeping. An abandoned order that nobody cancels expires by
itself at its `expiresAt`.
```bash
curl -X POST "{BASE_URL}/orders/296af5b6-f3b3-4128-b307-5ddc9190502f/cancel" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"reason": "customer abandoned checkout"
}
}'
```
```json
{
"orderId": "296af5b6-f3b3-4128-b307-5ddc9190502f",
"state": "CANCELLED"
}
```
#### Error handling
All order endpoints return a consistent error body with a human-readable `message`, a machine-readable `code`, optional per-field `details`, and a `hint` for resolution:
```json
{
"message": "Order cannot be submitted",
"code": "failed_precondition",
"details": [
{
"message": "A completed payment session is required to submit this order",
"code": "missing_payment_session",
"property": "paymentSessionId"
}
],
"hint": "Fetch the order to review its validation state and requirements, then retry."
}
```
Your order flow must handle these statuses:
| Status | When it happens |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Malformed request — inspect `details` for the offending property. |
| `401` | Missing or expired access token. |
| `403` | The API key or token does not grant access to this resource. |
| `404` | Unknown `orderId` or `lineItemId`. |
| `409` | The order is not in a state that allows the operation — for example, modifying or canceling an order after submission. |
| `412` | Submission preconditions are not met — the order is invalid or a `REQUIRED` requirement is unfulfilled. Re-fetch the order and inspect `validation` and `requirements`. |
| `429` | Rate limited — back off and retry. |
| `500` | Unexpected server error — safe to retry. |
Every order endpoint that changes something accepts an `X-Idempotency-Key` header. Send one
unique key per logical operation, and a retry becomes safe. The same key on the same request
returns the original result. The same key on a modified request gets a `409`. A key expires
after 24 hours.
#### Next steps
- [Order fulfillment](/developer-guide/use-cases/order-fulfillment.md) — Follow the order after submission: provisioning, activation, and fulfillment monitoring
- [Payment processing](/developer-guide/use-cases/payment-processing.md) — Create payment sessions and payment profiles to satisfy order requirements
### Order fulfillment
Canonical URL: https://docs.valdyr.tech/developer-guide/use-cases/order-fulfillment
Automate the complete order fulfillment process from order submission to service activation. This use case covers the workflows needed to provision telecommunications services, handle payments, and activate subscriptions for customers.
#### Prerequisites
You need all of these before you start:
- **Order management**: Understanding of order creation and submission flows
- **Payment processing**: Integration with payment collection systems
- **Service provisioning**: Access to subscription and license management endpoints
- **Inventory management**: Phone number inventory for mobile services
#### Overview
Order fulfillment encompasses the complete process after order creation:
1. Submit orders for processing
2. Handle payment collection and validation
3. Provision services and create subscriptions
4. Activate services and manage inventory
5. Monitor fulfillment status and handle exceptions
#### Step-by-step implementation
##### Step 1: Submit Order for Fulfillment
Transform draft orders into submitted orders ready for processing:
```bash
# Submit order for fulfillment
curl -X POST "{BASE_URL}/orders/{orderId}/submit" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"
# Monitor order status
curl -X GET "{BASE_URL}/orders/{orderId}" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"
```
##### Step 2: Handle payment collection
Create payment sessions to collect payment for orders:
```bash
# Create payment session
curl -X POST "{BASE_URL}/payment-sessions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"orderId": "296af5b6-f3b3-4128-b307-5ddc9190502f",
"paymentProvider": "STRIPE",
"hosted": true,
"returnUrl": "https://yourstore.com/success",
"cancelUrl": "https://yourstore.com/cancel"
}'
# Check payment status
curl -X GET "{BASE_URL}/payment-sessions/{paymentSessionId}" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"
```
##### Step 3: Reserve phone numbers (for mobile services)
Reserve phone numbers from inventory before service activation:
```bash
# Lease phone numbers
curl -X POST "{BASE_URL}/inventory/lease-numbers" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"quantity": 1,
"region": "SE",
"numberType": "mobile",
"preferences": {
"areaCode": "08"
}
}'
```
##### Step 4: Activate subscriptions
Activate subscription services after successful payment:
```bash
# List subscriptions for order
curl -X GET "{BASE_URL}/subscriptions?orderId={orderId}" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"
# Activate subscription
curl -X POST "{BASE_URL}/subscriptions/{subscriptionId}/activate" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"activationDate": "2024-01-15T10:00:00Z"
}'
```
#### Error handling and retry logic
Handle common fulfillment scenarios with proper error handling:
```javascript
// Comprehensive error handling for fulfillment
const handleFulfillmentError = async (error, orderId, step) => {
console.error(`Fulfillment error at step ${step}:`, error.message);
const errorHandling = {
payment_failed: {
action: 'retry_payment',
message: 'Payment collection failed - customer needs to retry payment',
},
inventory_unavailable: {
action: 'wait_inventory',
message: 'Phone numbers unavailable - waiting for inventory replenishment',
},
activation_failed: {
action: 'manual_review',
message: 'Service activation failed - requires manual intervention',
},
network_error: {
action: 'retry_with_backoff',
message: 'Network connectivity issue - will retry automatically',
},
};
const handling = errorHandling[error.code] || {
action: 'escalate',
message: 'Unknown error - escalating to support',
};
// Log error for monitoring
await logFulfillmentError(orderId, step, error, handling);
// Take appropriate action
switch (handling.action) {
case 'retry_payment':
return await createPaymentSession(orderId);
case 'wait_inventory':
return await retryWithBackoff(() => processStep(orderId, step));
case 'retry_with_backoff':
return await retryWithBackoff(() => processStep(orderId, step));
case 'manual_review':
return await escalateToSupport(orderId, error);
default:
throw error;
}
};
// Retry with exponential backoff
const retryWithBackoff = async (operation, maxRetries = 3) => {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
return await operation();
} catch (error) {
if (attempt === maxRetries) throw error;
const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
console.log(`Retry attempt ${attempt} failed, waiting ${delay}ms`);
await new Promise((resolve) => setTimeout(resolve, delay));
}
}
};
```
#### Webhook Integration
Set up webhooks to handle asynchronous fulfillment events:
```javascript
// Webhook handler for fulfillment events
const handleFulfillmentWebhook = (event) => {
switch (event.type) {
case 'order.submitted':
console.log('Order submitted:', event.data.orderId);
// Start fulfillment process
return initiateFulfillment(event.data.orderId);
case 'payment.completed':
console.log('Payment completed:', event.data.paymentId);
// Proceed with service activation
return processServiceActivation(event.data.orderId);
case 'subscription.activated':
console.log('Subscription activated:', event.data.subscriptionId);
// Send welcome notifications
return sendActivationNotification(event.data);
case 'fulfillment.completed':
console.log('Fulfillment completed:', event.data.orderId);
// Final cleanup and customer notification
return completeFulfillmentNotification(event.data);
case 'fulfillment.failed':
console.error('Fulfillment failed:', event.data);
// Handle fulfillment failure
return handleFulfillmentFailure(event.data);
default:
console.log('Unknown webhook event:', event.type);
}
};
// Express webhook endpoint example
app.post('/webhooks/connect', express.raw({ type: 'application/json' }), (req, res) => {
const event = JSON.parse(req.body);
try {
handleFulfillmentWebhook(event);
res.status(200).send('OK');
} catch (error) {
console.error('Webhook handling failed:', error);
res.status(500).send('Internal Server Error');
}
});
```
#### Complete fulfillment workflow
Put the steps together in one fulfillment orchestrator:
```javascript
// Complete fulfillment orchestrator
class OrderFulfillmentOrchestrator {
async processOrder(orderId) {
try {
console.log(`Starting fulfillment for order: ${orderId}`);
// Step 1: Submit order
const submittedOrder = await this.submitOrder(orderId);
// Step 2: Handle payment
const paymentSession = await this.createPaymentSession(orderId);
await this.waitForPaymentCompletion(paymentSession.paymentSessionId);
// Step 3: Reserve resources
const resources = await this.reserveResources(submittedOrder);
// Step 4: Activate services
const subscriptions = await this.activateServices(orderId);
// Step 5: Complete fulfillment
await this.completeFulfillment(orderId, subscriptions);
console.log(`Fulfillment completed successfully for order: ${orderId}`);
return { success: true, subscriptions };
} catch (error) {
console.error(`Fulfillment failed for order ${orderId}:`, error);
await this.handleFulfillmentError(error, orderId);
throw error;
}
}
async waitForPaymentCompletion(paymentSessionId, timeout = 300000) {
const startTime = Date.now();
while (Date.now() - startTime < timeout) {
const session = await this.checkPaymentStatus(paymentSessionId);
if (session.status === 'completed') {
return session;
} else if (session.status === 'failed' || session.status === 'cancelled') {
throw new Error(`Payment ${session.status}: ${session.failureReason}`);
}
// Poll every 5 seconds
await new Promise((resolve) => setTimeout(resolve, 5000));
}
throw new Error('Payment completion timeout');
}
async reserveResources(order) {
const resources = {};
// Reserve phone numbers for mobile services
for (const lineItem of order.lineItems) {
if (lineItem.productType === 'mobile') {
const phoneNumber = await this.leasePhoneNumbers({
quantity: 1,
region: order.customer.region,
});
resources[lineItem.lineItemId] = phoneNumber;
}
}
return resources;
}
}
// Usage example
const fulfillmentOrchestrator = new OrderFulfillmentOrchestrator();
// Process order fulfillment
fulfillmentOrchestrator
.processOrder('296af5b6-f3b3-4128-b307-5ddc9190502fe4567-e89b-12d3-a456-426614174000')
.then((result) => console.log('Fulfillment successful:', result))
.catch((error) => console.error('Fulfillment failed:', error));
```
#### Best practices
##### Fulfillment monitoring
- Log every fulfillment step.
- Set up alerts for failed fulfillments or unusual delays
- Track fulfillment metrics (completion time, success rate, failure reasons)
- Use correlation IDs to trace orders through the entire process
##### Resource management
- Reserve inventory (phone numbers) early in the process
- Implement inventory validation before order submission
- Handle inventory exhaustion gracefully with customer communication
- Clean up reserved resources if fulfillment fails
##### Payment handling
- Validate payment completion before service activation
- Implement payment retry mechanisms for failed transactions
- Handle partial payments appropriately
- Secure payment session data and comply with PCI standards
#### Next steps
After implementing order fulfillment:
- [Customer self-service](/developer-guide/use-cases/self-management.md) — A customer manages their own subscriptions and services
- [Payment processing](/developer-guide/use-cases/payment-processing.md) — Set up recurring billing and ongoing payment management
#### Common questions
**Q: How long does typical fulfillment take?**
A: The fulfillment time depends on the service type. A mobile service activates in 15 to 30 minutes. A specialized service can take longer.
**Q: What happens if payment fails during fulfillment?**
A: The order remains in a pending state. Payment sessions can be retried, or new payment methods can be collected.
**Q: Can I customize the fulfillment workflow?**
A: Yes, you can implement custom fulfillment logic using webhooks and the various API endpoints to match your business requirements.
### Orders and payments
Canonical URL: https://docs.valdyr.tech/developer-guide/use-cases/orders-and-payments
An order and a payment work together on every purchase. The order records what the customer
buys. The payment satisfies the payment requirement of that order, and the order cannot be
submitted before it does. You collect the payment through your own provider, or through a
managed payment session.
#### Core concept
Every order has **requirements** that must be met before submission:
- `requiresPayment`: Whether the order needs payment before it can be fulfilled
- `requiresPaymentProfile`: Whether a stored payment method is needed for future billing
- `requiresSigning`: Whether the order requires a digital signature
Each requirement is `NOT_REQUIRED`, `OPTIONAL`, or `REQUIRED`. Read them after you calculate
the price. They tell you the correct submission flow. An order with a total of zero can need
no payment at all. Read the requirements, and do not assume that a payment is due.
> **Note**
>
> The requirements are per order. One order can need a payment where the order before it did not.
#### Quick path
**1. Create order**
Create an order and add line items for the products the customer wants to buy.
**2. Read price**
Read the taxes and totals off the order to determine the amount due.
**3. Check requirements**
Inspect the order requirements to determine if payment, a payment profile, or signing is needed.
**4. Collect payment**
Collect payment through your own provider or use a managed payment session.
**5. Submit order**
Submit the order with the external payment reference to begin fulfillment. Orders paying through
a managed payment session or payment link are submitted automatically once the payment succeeds.
#### Choosing a payment approach
You have three ways to collect a payment. Use your own payment infrastructure, or use a
managed payment session.
- **Your own provider (Recommended)** — Collect the payment on your own payment stack, such as Stripe, Adyen, or Braintree. Pass the reference when you submit the order. You keep full control of the checkout, the payment methods, and the provider relationship.
- **Hosted payment page** — Use a managed payment session with `hosted: true`. The response carries a checkout URL that the provider hosts. Send the customer there. You build no payment interface.
- **Embedded payment widget** — Use a managed payment session with `hosted: false`. The response carries the provider credentials. Render the payment form in your own interface with the SDK of the provider.
##### When to use each approach
| Approach | Best for |
| ----------------------- | ---------------------------------------------------------------------------------------------------- |
| **Your own provider** | A team that already runs a payment infrastructure and wants control of the provider and the checkout |
| **Hosted payment page** | A fast integration that needs no payment components of its own |
| **Embedded widget** | A team that wants a managed payment backend, but its own payment interface |
> **Info**
>
> Most integrations collect the payment on their own provider. That way one payment relationship
> covers everything, and the checkout stays under their control.
#### 1. Create an order and add line items
Create an order for a customer and include the products they want to purchase.
```bash
curl -X POST "{BASE_URL}/orders" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"customerId": "123e4567-e89b-12d3-a456-426614174000"
},
"lineItems": [
{
"type": "SUBSCRIPTION",
"lineItemId": "sub-1",
"productOfferingId": "offering-id",
"subscriber": {
"name": "Jane Doe",
"email": "jane@example.com"
}
}
]
}'
```
You can also add line items to an existing order separately:
```bash
curl -X POST "{BASE_URL}/orders/{orderId}/line-items" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "ADDON",
"lineItemId": "addon-1",
"productOfferingId": "addon-offering-id",
"parentLineItemId": "sub-1"
}'
```
See [Create Order](/api-reference/orders.md#tag/orders/POST/orders) and [Add Line Items](/api-reference/orders.md#tag/orders/POST/orders/{orderId}/line-items)
#### 2. Read the price
Taxes and totals are recalculated whenever the order changes, so read them off the order before collecting payment.
```bash
curl "{BASE_URL}/orders/{orderId}" \
-H "X-API-Key: $API_KEY"
```
See [Get Order](/api-reference/orders.md#tag/orders/GET/orders/{orderId})
#### 3. Check order requirements
After calculating the price, inspect the order to determine what is needed before submission.
```bash
# Fetch the order and inspect the requirements object
curl "{BASE_URL}/orders/{orderId}" \
-H "X-API-Key: $API_KEY"
```
See [Get Order](/api-reference/orders.md#tag/orders/GET/orders/{orderId})
#### 4. Collect payment
Once you know the order requires payment, choose one of the following approaches.
##### Option A: Your own payment provider (recommended)
Collect the payment through your own payment provider: Stripe, Adyen, Braintree, or another
one. You keep full control of the checkout, and you keep the payment infrastructure that you
already run. This approach adds no dependency.
After collecting payment on your side, submit the order with an `externalPayment` reference:
```bash
# Step 1: Collect payment through your own provider
# (This happens in your existing payment flow)
# Step 2: Submit the order with the payment reference
curl -X POST "{BASE_URL}/orders/{orderId}/submit" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalPayment": {
"reference": "pi_3ABC123def456",
"receiptDescription": "Subscription activation payment",
"receiptUrl": "https://yourapp.com/receipts/abc123"
}
}'
```
The `externalPayment` object accepts:
| Field | Required | Description |
| -------------------- | -------- | ---------------------------------------------------------- |
| `reference` | Yes | The payment reference or transaction ID from your provider |
| `receiptDescription` | No | A human-readable description of the payment |
| `receiptUrl` | No | A URL to the payment receipt or confirmation page |
> **Note**
>
> When using external payments, you are responsible for collecting the correct amount and handling
> refunds through your payment provider.
See [Submit Order](/api-reference/orders.md#tag/orders/POST/orders/{orderId}/submit)
##### Option B: Hosted payment page
If you prefer a managed payment flow, create a payment session with `hosted: true` to get a checkout URL. Redirect the customer to the provider-hosted payment page.
```bash
curl -X POST "{BASE_URL}/payment-sessions" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"orderId": "{orderId}",
"paymentProvider": "STRIPE",
"hosted": true,
"returnUrl": "https://yourapp.com/payment/success",
"cancelUrl": "https://yourapp.com/payment/cancel"
}'
# Redirect the customer to provider.checkoutUrl from the response
```
After the customer completes payment, they are redirected to your `returnUrl`. There is no submit call to make — once the payment succeeds, the order is submitted automatically. Poll the order until it leaves `PENDING_PAYMENT`, or subscribe to the `order.statusChanged` webhook event.
```bash
# Poll the order state
curl "{BASE_URL}/orders/{orderId}" \
-H "X-API-Key: $API_KEY"
# When the payment succeeds, the state moves from PENDING_PAYMENT to SUBMITTED
```
See [Create Payment Session](/api-reference/payment-sessions.md#tag/payment-sessions/POST/payment-sessions) and [Get Payment Session](/api-reference/payment-sessions.md#tag/payment-sessions/GET/payment-sessions/{paymentSessionId})
##### Option C: Embedded payment widget
Create a payment session with `hosted: false` (or omit the field) to get provider credentials for rendering a payment form directly in your UI.
```bash
curl -X POST "{BASE_URL}/payment-sessions" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"orderId": "{orderId}",
"paymentProvider": "STRIPE"
}'
# Use provider.clientSecret and provider.publishableKey from the response
# to render a payment widget
```
Use the returned credentials with the provider's client SDK. For example, with Stripe Elements:
```javascript
const stripe = Stripe(publishableKey);
const elements = stripe.elements({ clientSecret });
const paymentElement = elements.create('payment');
paymentElement.mount('#payment-element');
// When the customer submits the form:
const { error } = await stripe.confirmPayment({
elements,
confirmParams: {
return_url: 'https://yourapp.com/payment/success',
},
});
```
After the payment completes, the order is submitted automatically — no submit call is needed. Poll the order until it leaves `PENDING_PAYMENT`, or subscribe to the `order.statusChanged` webhook event:
```bash
curl "{BASE_URL}/orders/{orderId}" \
-H "X-API-Key: $API_KEY"
# When the payment succeeds, the state moves from PENDING_PAYMENT to SUBMITTED
```
See [Create Payment Session](/api-reference/payment-sessions.md#tag/payment-sessions/POST/payment-sessions)
#### Zero-total orders with payment profile
An order with a total of zero can still need a stored payment method, as a trial subscription does. Submit that order with a payment profile session ID.
```bash
curl -X POST "{BASE_URL}/orders/{orderId}/submit" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"paymentProfileSessionId": "profile-session-id"
}'
```
#### Order states
| State | Description |
| ------------------ | ---------------------------------------------- |
| `PENDING` | The order is a cart. You can still change it |
| `PENDING_PAYMENT` | The order is locked and waits for the payment |
| `SUBMITTED` | You submitted the order for processing |
| `PENDING_APPROVAL` | The order waits for an approval |
| `PROCESSING` | The order is in fulfillment |
| `COMPLETED` | The platform fulfilled the order |
| `CANCELLED` | The order was canceled before it completed |
| `EXPIRED` | The order expired after a period of inactivity |
| `FAILED` | The fulfillment of the order failed |
#### Payment session statuses
| Status | Description |
| ----------------- | ------------------------------------------------- |
| `PENDING` | Session created, awaiting customer payment |
| `REQUIRES_ACTION` | The customer has one more step, such as 3D Secure |
| `COMPLETED` | Payment successfully collected |
| `FAILED` | Payment failed |
#### Requirements reference
When you retrieve an order after calculating the price, the `requirements` object tells you what is needed before submission.
| Requirement | Values | Description |
| ------------------------ | -------------------------------------- | ----------------------------------------- |
| `requiresPayment` | `NOT_REQUIRED`, `OPTIONAL`, `REQUIRED` | Whether payment must be collected |
| `requiresPaymentProfile` | `NOT_REQUIRED`, `OPTIONAL`, `REQUIRED` | Whether a stored payment method is needed |
| `requiresSigning` | `NOT_REQUIRED`, `OPTIONAL`, `REQUIRED` | Whether a digital signature is needed |
#### Next steps
- [Orders](/api-reference/orders.md) — Full order management API reference
- [Payment sessions](/api-reference/payment-sessions.md) — Managed payment session creation and management
- [Payment profiles](/api-reference/payment-profiles.md) — Stored payment methods for recurring billing
- [Webhooks](/api-reference/webhooks.md) — Set up notifications for order and payment events
### Payment processing
Canonical URL: https://docs.valdyr.tech/developer-guide/use-cases/payment-processing
This guide covers payment processing for a telecom service from end to end. It takes you
through the first collection, the stored payment methods, the billing, and a failed payment.
#### Prerequisites
You need all of these before you start:
- **Order management**: Understanding of order creation and pricing flows
- **Customer management**: Active customers with subscription services
- **Payment gateway integration**: Access to payment processors (cards, bank transfers, digital wallets)
- **Billing system**: Understanding of billing cycles and pricing models
- **Compliance**: PCI DSS compliance for handling payment data
#### Overview
Payment processing encompasses:
1. Payment session creation for secure payment collection
2. Payment profile management for stored payment methods
3. Payment processing and transaction handling
4. Payment failure management and retry logic
5. Billing and invoice management
6. Promotional pricing and discount handling
#### Step-by-step implementation
##### Step 1: Create payment sessions for orders
Create secure payment sessions to collect payment for orders:
```bash
# Create payment session for order
curl -X POST "{BASE_URL}/payment-sessions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"orderId": "123e4567-e89b-12d3-a456-426614174000",
"paymentProvider": "STRIPE",
"hosted": true,
"returnUrl": "https://yourstore.com/payment/success",
"cancelUrl": "https://yourstore.com/payment/cancel"
}'
# Check payment session status
curl -X GET "{BASE_URL}/payment-sessions/{paymentSessionId}" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"
```
##### Step 2: Manage payment profiles
Set up stored payment methods for recurring billing:
```bash
# Create payment profile session
curl -X POST "{BASE_URL}/payment-profiles/sessions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"returnUrl": "https://yourstore.com/billing/payment-methods",
"paymentMethods": ["card", "bank_account"]
}'
# Get payment profiles
curl -X GET "{BASE_URL}/payment-profiles" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"
```
##### Step 3: Process payments
Handle payment processing and transaction management:
```bash
# List payments
curl -X GET "{BASE_URL}/payments?customerId={customerId}&limit=50" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"
# Get payment details
curl -X GET "{BASE_URL}/payments/{paymentId}" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"
```
#### Handling payment failures and retries
Handle a failed payment with retry logic:
```javascript
// Payment failure handler with exponential backoff
class PaymentRetryHandler {
constructor(maxRetries = 3) {
this.maxRetries = maxRetries;
this.retryDelays = [24, 72, 168]; // Hours: 1 day, 3 days, 1 week
}
async handlePaymentFailure(paymentSessionId, failureReason) {
console.log(`Payment failed for session ${paymentSessionId}: ${failureReason}`);
// Get payment session details
const session = await checkPaymentSessionStatus(paymentSessionId);
const customer = await getOrderCustomer(session.orderId);
// Categorize failure type
const failureCategory = this.categorizeFailure(failureReason);
switch (failureCategory) {
case 'insufficient_funds':
await this.scheduleRetry(paymentSessionId, 24); // Retry in 24 hours
await this.notifyCustomer(customer.customerId, 'insufficient_funds');
break;
case 'expired_card':
await this.requestPaymentMethodUpdate(customer.customerId);
break;
case 'fraud_suspected':
await this.escalateToFraud(session);
break;
case 'technical_error':
await this.scheduleRetry(paymentSessionId, 1); // Retry in 1 hour
break;
default:
await this.escalateToSupport(session);
}
}
categorizeFailure(reason) {
const failureMap = {
insufficient_funds: 'insufficient_funds',
card_declined: 'insufficient_funds',
expired_card: 'expired_card',
invalid_cvc: 'expired_card',
fraud_suspected: 'fraud_suspected',
processing_error: 'technical_error',
network_error: 'technical_error',
};
return failureMap[reason] || 'unknown';
}
async scheduleRetry(paymentSessionId, delayHours) {
// In production, this would schedule a background job
setTimeout(
async () => {
try {
// Create new payment session with same order
const originalSession = await checkPaymentSessionStatus(paymentSessionId);
const customer = await getOrderCustomer(originalSession.orderId);
const newSession = await createOrderPaymentSession(originalSession.orderId);
// Notify customer of retry attempt
await this.notifyCustomerRetry(customer.customerId, newSession.hostedUrl);
} catch (error) {
console.error('Payment retry failed:', error);
}
},
delayHours * 60 * 60 * 1000,
);
}
async notifyCustomer(customerId, failureType) {
// Implement customer notification logic
console.log(`Notifying customer ${customerId} about ${failureType}`);
}
async requestPaymentMethodUpdate(customerId) {
// Create payment profile session for updating payment method
const session = await createPaymentProfileSession(
`${process.env.BASE_URL}/billing/update-payment`,
{ customerId },
);
// Send email with update link
await this.notifyCustomer(customerId, 'payment_method_update_required');
}
}
```
#### Promotional pricing and discounts
Handle promotional codes and discount applications:
```javascript
// Get promotion by promo code
const getPromotionByCode = async (promoCode) => {
const response = await fetch(`{BASE_URL}/discounts/promotions/promo-code/${promoCode}`, {
method: 'GET',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
});
if (!response.ok) {
const error = await response.json();
throw new Error(`Invalid promo code: ${error.message}`);
}
return await response.json();
};
// Apply promo code to an order and re-price it
const applyPromoCodeToOrder = async (orderId, promoCode) => {
try {
// Validate promo code first
const promotion = await getPromotionByCode(promoCode);
// The promo code lives on the order itself
const updateResponse = await fetch(`{BASE_URL}/orders/${orderId}`, {
method: 'PUT',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({ promoCode }),
});
if (!updateResponse.ok) {
const error = await updateResponse.json();
throw new Error(`Failed to apply promo code: ${error.message}`);
}
// Read the order back to see the promotion applied
const pricingResponse = await fetch(`{BASE_URL}/orders/${orderId}`, {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-API-Key': 'YOUR_API_KEY',
},
});
if (!pricingResponse.ok) {
const error = await pricingResponse.json();
throw new Error(`Reading the order failed: ${error.message}`);
}
const { pricing } = await pricingResponse.json();
const discountsMinor = (pricing.lineItems ?? []).reduce(
(sum, item) => sum + (item.totalDiscountsMinor ?? 0),
0,
);
// Amounts are integers in the minor units of pricing.currency: 2749 is $27.49
return {
subtotalMinor: pricing.subtotalMinor,
discountsMinor,
totalMinor: pricing.totalMinor,
currency: pricing.currency,
promotion,
};
} catch (error) {
console.error('Failed to apply promo code:', error);
throw error;
}
};
// Promo code component
const PromoCodeInput = ({ orderId, onApplied, onError }) => {
const [promoCode, setPromoCode] = useState('');
const [loading, setLoading] = useState(false);
const [applied, setApplied] = useState(null);
const handleApply = async () => {
if (!promoCode.trim()) return;
setLoading(true);
try {
const result = await applyPromoCodeToOrder(orderId, promoCode);
setApplied(result);
onApplied(result);
} catch (error) {
onError(error.message);
} finally {
setLoading(false);
}
};
return (
✓ {applied.promotion.discount.description} applied
Discount: - {new Intl.NumberFormat('en-US', { style: 'currency', currency: applied.currency, }).format(applied.discountsMinor / 100)}