Fulfillment and Returns

Overview

Two resources — packages and returns — cover the post-order lifecycle. Both follow the atomic-create pattern: a single POST creates the parent resource plus all inline children in one transactional write, returning the fully hydrated response. You never need follow-up calls to add items or purchase a label.

Resource	Endpoint	Inline children
Package	`POST /v1/packages`	`items[]`, optional label purchase, optional fulfill
Return (RMA)	`POST /v1/returns`	`items[]`, optional auto-refund, restocking fee

Packages

Canonical scenario: package with items + label + fulfill in one POST

This request creates the package, adds two line items, purchases a Shippo label, and fulfills the package (posts GL entries, sends shipment notification) in a single atomic call.

curl -s -X POST "https://api.arcuserp.com/v1/packages" \
  -H "Authorization: Bearer ark_live_ent_wss_abc123xyz" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "order_id": "ORDER_UUID",
    "carrier_service": "ups_ground",
    "items": [
      {
        "order_item_id": "ORDER_ITEM_UUID_1",
        "quantity": 2,
        "serial_numbers": ["SN001", "SN002"]
      },
      {
        "order_item_id": "ORDER_ITEM_UUID_2",
        "quantity": 1
      }
    ],
    "buy_label": true,
    "rate_object_id": "SHIPPO_RATE_OBJECT_ID",
    "fulfill_after_label": true
  }'

import Arcus from "@arcuserp/typescript-sdk";

const client = new Arcus({ apiKey: "ark_live_ent_wss_abc123xyz" });

const pkg = await client.packages.create({
  order_id: "ORDER_UUID",
  carrier_service: "ups_ground",
  items: [
    { order_item_id: "ORDER_ITEM_UUID_1", quantity: 2, serial_numbers: ["SN001", "SN002"] },
    { order_item_id: "ORDER_ITEM_UUID_2", quantity: 1 },
  ],
  buy_label: true,
  rate_object_id: "SHIPPO_RATE_OBJECT_ID",
  fulfill_after_label: true,
});

console.log(pkg.data.label_url);       // https://api.goshippo.com/...
console.log(pkg.data.tracking_number); // 1Z999AA10123456784
console.log(pkg.data.fulfilled_at);    // 2026-05-12T...

from arcuserp import Arcus

client = Arcus(api_key="ark_live_ent_wss_abc123xyz")

pkg = client.packages.create(
    order_id="ORDER_UUID",
    carrier_service="ups_ground",
    items=[
        {"order_item_id": "ORDER_ITEM_UUID_1", "quantity": 2, "serial_numbers": ["SN001", "SN002"]},
        {"order_item_id": "ORDER_ITEM_UUID_2", "quantity": 1},
    ],
    buy_label=True,
    rate_object_id="SHIPPO_RATE_OBJECT_ID",
    fulfill_after_label=True,
)

print(pkg.data["label_url"])
print(pkg.data["tracking_number"])

Response

{
  "data": {
    "id": "PKG_UUID",
    "package_id": "SO-1234-B1",
    "order_id": "ORDER_UUID",
    "entity_id": "ENTITY_UUID",
    "carrier": "ups",
    "service": "ground",
    "status": "packed",
    "fulfillment_status": "fulfilled",
    "items": [
      {
        "id": "PKG_ITEM_UUID_1",
        "order_item_id": "ORDER_ITEM_UUID_1",
        "quantity": 2,
        "serial_numbers": ["SN001", "SN002"]
      },
      {
        "id": "PKG_ITEM_UUID_2",
        "order_item_id": "ORDER_ITEM_UUID_2",
        "quantity": 1
      }
    ],
    "label_url": "https://api.goshippo.com/labels/...",
    "tracking_number": "1Z999AA10123456784",
    "label_purchased_at": "2026-05-12T14:32:00Z",
    "fulfilled_at": "2026-05-12T14:32:05Z",
    "weight": 2.5,
    "length": 12,
    "width": 9,
    "height": 6,
    "created_at": "2026-05-12T14:31:58Z"
  }
}

POST /v1/packages returns 409 revision_unacknowledged when the order was revised after the customer received it and the customer has not yet acknowledged the new total. Acknowledge the revision with POST /v1/orders/:id/customer-acknowledge-revision first.

Inline create options

Field	Type	Description
`order_id`	string	Required. Parent sales order UUID.
`items[]`	array	Line items to add. Each item: `order_item_id` (required), `quantity` (required), `serial_numbers[]` (optional, for serialized products).
`carrier_service`	string	Compound carrier+service string (`ups_ground`, `fedex_priority_overnight`). Mapped to `carrier` + `service` fields automatically.
`carrier` + `service`	strings	Alternative to `carrier_service`. Both must be provided.
`buy_label`	boolean	If `true`, purchase a Shippo label after package creation. Requires `rate_object_id`.
`rate_object_id`	string	Required with `buy_label: true`. Fetch rates via `GET /v1/packages/:id/rates`.
`label_file_type`	string	Optional label format: `PDF`, `PNG`, or `ZPLII`.
`fulfill_after_label`	boolean	If `true`, transition the package to fulfilled after label purchase. Posts GL entries, deducts inventory, queues shipment notification. Only fires if `buy_label: true` and label purchase succeeds.

Separate label purchase (two-step flow)

If you prefer to separate rate shopping from package creation:

# Step 1: Create package
PKG_ID=$(curl -s -X POST ".../v1/packages" \
  -d '{"order_id": "ORDER_UUID", "items": [...]}' | jq -r '.data.id')

# Step 2: Fetch rates
RATE_ID=$(curl -s ".../v1/packages/$PKG_ID/rates" | jq -r '.data[0].object_id')

# Step 3: Buy label
curl -s -X POST ".../v1/packages/$PKG_ID/buy-label" \
  -d "{\"rate_object_id\": \"$RATE_ID\"}"

# Step 4: Fulfill
curl -s -X POST ".../v1/packages/$PKG_ID/fulfill"

Package lifecycle

draft -> packed -> label_created -> shipped (fulfilled) -> delivered
                -> void-label returns the package to an un-labeled state
shipped or delivered -> returned

GET /v1/packages/:id/rates — live carrier rates, cheapest first, to get the rate_object_id (needs fulfillment:read)
POST /v1/packages/:id/buy-label — purchase the label with a previously fetched rate (needs fulfillment:write)
POST /v1/packages/:id/void-label — void the active label with the carrier; returns 422 and leaves the label in place if the carrier void call fails
POST /v1/packages/:id/fulfill — mark the package fulfilled, post the cost-of-goods, revenue, tax, shipping and discount journal entries, update any connected marketplace tracking, and send the shipment email
GET /v1/tracking-events?package_id=:id — carrier tracking events; a package_id or order_id filter is required, otherwise the call returns 400

buy-label and GET /v1/packages/:id/rates both return 409 order_not_spendable when the package’s order is cancelled, archived, or expired, because a terminal order cannot buy carrier labels. fulfill returns 409 when the package is already fulfilled or an item is missing its serial numbers, and 422 cannot_fulfill_empty_package when the package has no items.

Shippo not configured

If the entity has no Shippo credentials, buy_label: true returns:

{
  "error": "connector_not_configured",
  "code": "connector_not_configured",
  "type": "connector_error",
  "hint": "Shippo is not configured for this entity. Add credentials in Settings > Integrations.",
  "package": { "id": "PKG_UUID", "..." }
}

The package is created and returned in the error body so you can retry buy-label after configuring Shippo.

Webhook delivery: the fulfillment.shipped event is queued when a package is marked shipped and delivered to any webhook endpoint subscribed to it. See Your First Webhook to register one. To follow a shipment after that, poll GET /v1/tracking-events?package_id=:id.

Adding items to an existing package

POST /v1/packages/:id/items enforces two invariants before inserting:

Item-on-order — the product must be on the parent order. Off-order adds return 422 product_not_on_order.
Quantity cap — requested qty must not exceed ordered_qty - already_packed_qty across ALL packages on the order. Over-cap adds return 422 package_quantity_exceeds_ordered.

Either order_item_id OR product_id may be supplied; the canonical writer resolves the matching order_item when only product_id is provided.

422 product_not_on_order

{
  "error": "product_not_on_order",
  "code": "product_not_on_order",
  "type": "validation_error",
  "param": "product_id",
  "hint": "This product is not on the parent order. To add it, edit the order first, then return to packing.",
  "product_id": "8a3f...",
  "order_id": "c7e1..."
}

422 package_quantity_exceeds_ordered

{
  "error": "package_quantity_exceeds_ordered",
  "code": "package_quantity_exceeds_ordered",
  "type": "validation_error",
  "param": "quantity",
  "hint": "You can pack at most 2 more units of this product on this order (3 already packed; 5 ordered).",
  "ordered_qty": 5,
  "already_packed_qty": 3,
  "remaining_qty": 2,
  "product_id": "8a3f..."
}

To preview what’s still packable on an order, call GET /v1/orders/:id/items?packable=true. The response includes one row per (order_id, product_id) with ordered_qty, already_packed_qty, remaining_qty.

Automatic packing and pack leftovers

POST /v1/fulfillment/pack-order packs an unpacked or partially packed order into one or more optimally sized packages using the entity’s active box inventory. It allocates inventory and, with auto_rate: true, fetches rates for each package; auto_buy_label: true also buys the labels, and needs auto_rate: true and a configured shipping rule.

curl -s -X POST "https://api.arcuserp.com/v1/fulfillment/pack-order" \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "order_id": "ORDER_UUID", "auto_rate": true, "auto_buy_label": false }'

It needs the fulfillment:write scope plus the fulfillment.pack permission. If the order is already fully packed it returns 409 all_items_already_packed and does nothing. When the order cannot be packed it returns 400 no_active_boxes_configured if the entity has no active box products (add boxes in Products), or 400 no_boxes_for_location if none of the boxes is available at the order’s location (assign a box to that location in Products). Both are returned before the packing service is called. Otherwise it returns 422 with one of these codes:

Code	Meaning	What to do
`packpilot_item_too_large`	An item’s dimensions exceed every allowed box	Add a larger box or correct the item’s shipping dimensions
`packpilot_circuit_open`	Arcus Mighty has paused after too many recent errors	Retry in a few minutes or create packages manually
`location_shortfall_blocks_pack`	Every packable line is out of stock at the order’s location; the response lists `short_lines[]` with stock at other locations	Transfer or receive stock, or change the order’s location, then retry
`SHIP_COMPLETE_BLOCKED`	The order is ship complete and one or more lines lack the inventory to pack fully; the response lists `short_lines[]`	Wait until every line can ship, or change the order
`repack_blocked_label_void_failed`	A repack was attempted but an existing label could not be voided	Resolve the label with the carrier, then retry

When Pack with Mighty cannot fit one or more items into any available box, those items are kept as leftovers rather than silently dropped. Leftovers are shown to the warehouse operator on the Pack Order page and the Order Detail > Fulfillment tab, where the operator packs them by hand, dismisses them with a note, backorders them, or splits them to a new order. The public API has no leftovers operations, so list and resolve leftovers in the Arcus app.

Returns (RMAs)

Canonical scenario: return with items + restocking fee + auto-refund

This creates the RMA, adds line items, and issues the refund in a single atomic call.

curl -s -X POST "https://api.arcuserp.com/v1/returns" \
  -H "Authorization: Bearer ark_live_ent_wss_abc123xyz" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "original_order_id": "ORDER_UUID",
    "reason": "wrong_item",
    "refund_amount": 150.00,
    "items": [
      {
        "order_item_id": "ORDER_ITEM_UUID_1",
        "quantity": 1,
        "condition": "new"
      }
    ],
    "restocking_fee": { "type": "percentage", "value": 10 },
    "auto_refund": true,
    "refund_payment_id": "PAYMENT_UUID"
  }'

import Arcus from "@arcuserp/typescript-sdk";

const client = new Arcus({ apiKey: "ark_live_ent_wss_abc123xyz" });

const rma = await client.returns.create({
  original_order_id: "ORDER_UUID",
  reason: "wrong_item",
  refund_amount: 150.00,
  items: [
    { order_item_id: "ORDER_ITEM_UUID_1", quantity: 1, condition: "new" },
  ],
  restocking_fee: { type: "percentage", value: 10 },
  auto_refund: true,
  refund_payment_id: "PAYMENT_UUID",
});

console.log(rma.data.return_number);     // RMA-00042
console.log(rma.data.restocking_fee);    // 15  (10% of 150)
console.log(rma.data.items.length);      // 1
console.log(rma.data.refund?.id);        // refund record id

from arcuserp import Arcus

client = Arcus(api_key="ark_live_ent_wss_abc123xyz")

rma = client.returns.create(
    original_order_id="ORDER_UUID",
    reason="wrong_item",
    refund_amount=150.00,
    items=[
        {"order_item_id": "ORDER_ITEM_UUID_1", "quantity": 1, "condition": "new"},
    ],
    restocking_fee={"type": "percentage", "value": 10},
    auto_refund=True,
    refund_payment_id="PAYMENT_UUID",
)

print(rma.data["return_number"])  # RMA-00042
print(rma.data["restocking_fee"]) # 15

Response

{
  "data": {
    "id": "RETURN_UUID",
    "return_number": "RMA-00042",
    "entity_id": "ENTITY_UUID",
    "original_order_id": "ORDER_UUID",
    "status": "authorized",
    "reason": "wrong_item",
    "refund_amount": 150.0,
    "restocking_fee": 15.0,
    "restocking_fee_auto_applied": false,
    "items": [
      {
        "id": "RETURN_ITEM_UUID",
        "order_item_id": "ORDER_ITEM_UUID_1",
        "quantity_authorized": 1,
        "condition": "new",
        "disposition": "pending"
      }
    ],
    "refund": {
      "id": "REFUND_UUID",
      "amount": 135.0,
      "payment_method": "card",
      "status": "succeeded"
    },
    "created_at": "2026-05-12T14:32:00Z"
  }
}

Inline create options

Field	Type	Description
`original_order_id`	string	The originating sales order. Required unless this is a standalone RMA.
`account_id`	string	The customer account. Derived from the original order when `original_order_id` is given.
`reason`	string	Free-text reason for the return.
`refund_amount`	number	Total dollar amount to refund (before restocking fee).
`items[]`	array	Line items to return. Fields: `order_item_id` or `product_id`, `quantity` (alias for `quantity_authorized`), `condition` (enum: `new`, `used`, `damaged`, `defective`), `reason_code` (enum: `defective`, `damaged_in_transit`, `wrong_item_shipped`, `not_as_described`, `no_longer_needed`, `found_better_price`, `arrived_late`, `other`, `unspecified`), `notes`.
`restocking_fee`	number or object	Flat dollar amount OR `{ "type": "percentage", "value": 10 }` (10% of `refund_amount`). Also accepts `{ "type": "flat", "value": 30 }`.
`auto_refund`	boolean	If `true`, issue the refund immediately after RMA creation. Requires `refund_payment_id` and the `payments:write` scope. The response then carries a `refund` object.
`refund_payment_id`	string	Required with `auto_refund: true`. The original payment UUID to refund against.
`refund_method`	string	Optional. `original` (default), `store_credit`, `check`, `cash`.
`override_window`	boolean	If `true`, bypasses the entity’s return-window-days guard.
`customer_initiated`	boolean	Set to `true` when the return was initiated via the customer portal.
`notes`	string	Optional notes on the return.
`metadata`	object	Optional key-value pairs stored on the return.

Restocking fee formats

// Flat dollar amount
"restocking_fee": 25.00

// 10% of refund_amount
"restocking_fee": { "type": "percentage", "value": 10 }

// Explicit flat type (same as flat number)
"restocking_fee": { "type": "flat", "value": 25.00 }

All three formats store the computed flat amount in returns.restocking_fee and return it as a JS number.

RMA lifecycle

authorized -> expected (label sent to customer) -> received -> inspecting? -> restocked / written_off / sent_to_vendor -> closed
authorized -> cancelled

POST /v1/returns/:id/receive — record physical receipt of the returned goods without the full inspection and disposition workflow, for simple receive-and-restock flows
POST /v1/returns/:id/inspect — move the return to inspecting when a per-item condition assessment is needed
POST /v1/returns/:id/disposition — record what happened to each item: restock, write off, destroy, send to the vendor, exchange, or quarantine
POST /v1/returns/:id/refund — issue an explicit refund when it was not done inline
POST /v1/returns/:id/cancel — cancel a pending_approval, authorized or expected return that has nothing received, and release any inventory holds

All five calls accept an Idempotency-Key header and need the returns:write scope.

Receiving and disposition (separate calls)

After the physical goods arrive:

# Receive the goods (restores inventory)
curl -X POST "https://api.arcuserp.com/v1/returns/$RMA_ID/receive" \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "items": [{ "return_item_id": "ITEM_UUID", "quantity_received": 1, "receiving_location_id": "LOCATION_UUID" }] }'

# Disposition (posts COGS reversal GL entries)
curl -X POST "https://api.arcuserp.com/v1/returns/$RMA_ID/disposition" \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "items": [{ "return_item_id": "ITEM_UUID", "disposition": "restock", "quantity": 1 }] }'

receive takes return_item_id, quantity_received and receiving_location_id for every line, and optionally serial_numbers[]. disposition takes return_item_id, disposition (restock, writeoff, destroyed, vendor_return, exchange, or quarantine) and quantity for every line, plus optional final_location_id and condition (new, like_new, good, fair, damaged, or defective). A line whose condition is damaged or defective can be restocked only with force_restock: true and a force_restock_reason. These errors can come back from receive:

Status and code	Meaning
`400 rma_already_received`	The return is already received with units counted in. A later lot is refused instead of being posted a second time (the first receipt from `authorized` is accepted).
`409 rma_movement_not_written`	The stock movement this step pairs with matched a movement the return already posted, so nothing was booked. The step is refused and rolled back so the goods, the received counters and the general ledger cannot disagree. Refresh the return and check where the units are before retrying.
`422 kit_has_no_components`	A kit line has no exploded components to receive, so no stock could move.
`422 no_receiving_location`	No receiving location was given or resolved for a physical line.

disposition returns the same 409 rma_movement_not_written when its stock movement was already posted.

Refunding a return

POST /v1/returns/:id/refund refunds a received, inspected, restocked, written-off, sent-to-vendor, or closed return. Send an optional amount, a payment_method (original, store_credit, check, or cash), a reason, and optionally allocations[] (each with a payment_id and amount) to split the refund across the original payments. It needs the returns:write and payments:write scopes plus the payments.refund_void permission. Calling it again with the same amount returns the cached result (idempotent: true); a different amount returns 409 refund_already_issued. The other refusals are:

Status and code	Meaning
`409 refund_on_hold`	Accounting put this return’s refund on hold with a question for the office. Nothing is refunded until the office answers, which releases the hold. `meta.refund_hold` carries the return, the question, who held it and when.
`409 state_transition_invalid`	The return is not in a status a refund is allowed from.
`409 already_settled`	What is owed on this return is already settled, so refunding more would refund the customer twice.

Cancelling a return

POST /v1/returns/:id/cancel takes an optional reason. It needs the returns:write scope plus the returns.cancel permission, and works only while the return is pending_approval, authorized or expected and no unit has been received. It returns 409 cannot_cancel_items_received once any unit is received, and a 409 from any other state; cancelling an already-cancelled return returns 200.

Return-window enforcement

If entities.settings.return_window_days is set, returns outside the window are rejected with 422 outside_return_window. Pass override_window: true to bypass (requires returns:write scope).

Validating serials on return

For serialized products, Arcus can verify that the scanned serial was actually sold on the order being returned before persisting it. This prevents swap fraud and inventory drift.

Entity setting

Configure the validation mode in Settings > Shipping & Fulfillment > Returns, or via the API:

curl -X PATCH "https://api.arcuserp.com/v1/entities/$ARCUS_ENTITY_ID/settings" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{ "settings": { "returns": { "serial_validation_mode": "hard" } } }'

Mode	Behavior
`off`	Skip validation (default, backwards-compatible).
`warn`	Validate, log mismatches server-side, let the receive/disposition proceed.
`hard`	Validate and reject with `422` if the serial was not on the original shipment.

Probing a serial before submit

Call POST /v1/serials/validate-for-return (needs serials:read) to check a serial before submitting the receive. It changes nothing and always answers 200 with a verdict, so check the valid field rather than the status code. The receive and disposition calls enforce the actual gate:

curl -X POST "https://api.arcuserp.com/v1/serials/validate-for-return" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "SN001",
    "original_order_id": "ORDER_UUID",
    "product_id": "PRODUCT_UUID"
  }'

Response shapes:

// Serial is valid for this return
{ "data": { "valid": true, "serial_id": "SN_UUID", "status": "sold", "order_number": "SO-0042" } }

// Serial does not match the original order
{ "data": { "valid": false, "code": "serial_not_on_original_order", "hint": "Serial SN001 is linked to a different order." } }

// No original_order_id was supplied (cannot validate)
{ "data": { "valid": null, "reason": "no_original_order" } }

Error codes (hard mode)

When serial_validation_mode is hard and a receive/disposition is submitted with a mismatched serial, the endpoint returns 422 with a structured error:

Code	Meaning
`serial_not_found`	No serial with that number exists for this entity + product.
`serial_not_on_original_order`	Serial exists but was not sold on this RMA’s source order.
`serial_not_sold`	Serial is not in `sold` status (cannot be returned).
`serial_already_returned`	Serial has already been returned on a previous RMA.

Scopes required

Operation	Scope
List / read packages or returns	`fulfillment:read` / `returns:read`
Create / update / fulfill packages	`fulfillment:write`
Create / receive / disposition returns	`returns:write`
Refund (via `POST /v1/returns/:id/refund` or `auto_refund`)	`returns:write` + `payments:write`, plus the `payments.refund_void` permission for the refund call
Cancel a return	`returns:write`, plus the `returns.cancel` permission
Rates for a package	`fulfillment:read`
Pack an order automatically	`fulfillment:write`, plus the `fulfillment.pack` permission
Validate a serial for a return	`serials:read`
Update entity settings	`settings:write`
Create exchange order	`returns:write` + `orders:write`
Create return label	`returns:write` + `fulfillment:write`
Capture serials	`serials:write`
Delete a serial	`serials:delete`

Serial capture during pack

Serialized products require one serial number per unit before a package can be fulfilled. The public API captures serials progressively as units are scanned, with POST /v1/serials/capture-partial, which needs the serials:write scope.

Capture serials for a package line

Send package_item_id and product_id, plus either raw_barcodes[] or serial_numbers[]. When you send raw_barcodes[], the backend runs barcode parsing (prefix stripping, format normalization, lot extraction) automatically. Optional fields are order_id, package_id, lot_number, expiry_date, notes, and source.

curl

curl -s -X POST "https://api.arcuserp.com/v1/serials/capture-partial" \
  -H "Authorization: Bearer ark_live_ent_wss_abc123xyz" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "package_item_id": "PKG_ITEM_UUID",
    "product_id": "PRODUCT_UUID",
    "raw_barcodes": ["1234567890123"]
  }'

{
  "data": {
    "captured_count": 1,
    "total_required": 3,
    "remaining": 2,
    "partial": true,
    "serials": [{ "id": "...", "serial_number": "1234567890123", "status": "allocated" }]
  }
}

The call answers 201 and marks each captured serial allocated. Call it again as each additional unit is scanned. The partial flag stays true while remaining is above 0; when remaining reaches 0 and partial is false, the line is ready to fulfill.

Status and code	Meaning
`404` with error `Package item not found` (no `code`)	The package line does not exist for this entity.
`409` with error `Serial <n> already exists and is <status> on <order>` (no `code`)	The serial already exists and is allocated or sold, here or on another order.
`422 serial_over_capacity`	More serials were scanned than the line needs; the `hint` says how many to remove.
`422 barcode_parse_failed`	One or more scanned barcodes could not be parsed; `failures` lists them.

Removing a serial

The public API has no operation that releases a captured serial from its package line. DELETE /v1/serials/:id (needs serials:delete) soft-deletes a serial, which can be restored later with POST /v1/serials/:id/restore, and it returns 409 cannot_delete_serial_in_use while the serial is allocated or sold. To change a serial you already captured, release it in the Arcus app. When an order is already fulfilled, use the RMA flow (POST /v1/returns) to return the serialized unit.

Error handling

All errors follow the { error, code, type, hint } envelope. Partial-success responses (e.g. package created but label failed) include the created resource in the response body alongside the error:

{
  "error": "label_purchase_failed",
  "code": "label_purchase_failed",
  "type": "connector_error",
  "hint": "Package was created but label purchase failed. Retry via POST /v1/packages/:id/buy-label.",
  "package": { "id": "PKG_UUID", "..." }
}

This lets you recover without duplicating the package — just retry buy-label using the package.id from the error body.

Get Started

Concepts

Guides

SDKs

Collections

Overview

Packages

Canonical scenario: package with items + label + fulfill in one POST

Response

Inline create options

Separate label purchase (two-step flow)

Package lifecycle

Shippo not configured

Adding items to an existing package

Automatic packing and pack leftovers

Returns (RMAs)

Canonical scenario: return with items + restocking fee + auto-refund

Response

Inline create options

Restocking fee formats

RMA lifecycle

Receiving and disposition (separate calls)

Refunding a return

Cancelling a return

Return-window enforcement

Validating serials on return

Entity setting

Probing a serial before submit

Error codes (hard mode)

Scopes required

Serial capture during pack

Capture serials for a package line

Removing a serial

Error handling

​Overview

​Packages

​Canonical scenario: package with items + label + fulfill in one POST

​Response

​Inline create options

​Separate label purchase (two-step flow)

​Package lifecycle

​Shippo not configured

​Adding items to an existing package

​Automatic packing and pack leftovers

​Returns (RMAs)

​Canonical scenario: return with items + restocking fee + auto-refund

​Response

​Inline create options

​Restocking fee formats

​RMA lifecycle

​Receiving and disposition (separate calls)

​Refunding a return

​Cancelling a return

​Return-window enforcement

​Validating serials on return

​Entity setting

​Probing a serial before submit

​Error codes (hard mode)

​Scopes required

​Serial capture during pack

​Capture serials for a package line

​Removing a serial

​Error handling

Overview

Packages

Canonical scenario: package with items + label + fulfill in one POST

Response

Inline create options

Separate label purchase (two-step flow)

Package lifecycle

Shippo not configured

Adding items to an existing package

Automatic packing and pack leftovers

Returns (RMAs)

Canonical scenario: return with items + restocking fee + auto-refund

Response

Inline create options

Restocking fee formats

RMA lifecycle

Receiving and disposition (separate calls)

Refunding a return

Cancelling a return

Return-window enforcement

Validating serials on return

Entity setting

Probing a serial before submit

Error codes (hard mode)

Scopes required

Serial capture during pack

Capture serials for a package line

Removing a serial

Error handling