Orders

Endpoints for listing orders, viewing order details, listing order items, and creating checkout orders.

List orders

GET /orders

List orders for your team.

Scope: orders.lists

Description: Returns orders for your team. API tokens are automatically limited to their own team, even if filters.team_ids is sent in the request. Each order includes a checkout_link when its status is not PAID (otherwise null).

Parameters

ParameterTypeDescription
limitnumberNumber of records per page
pagenumberPage number
sort_bystringField to sort by
order_bystringSort direction (asc or desc)

Request

curl "https://api.presscart.com/orders?limit=10&page=1" \
  -H "Authorization: Bearer $PRESSCART_API_TOKEN"

Response

{
  "records": [
    {
      "id": "44444444-4444-4444-4444-444444444444",
      "profile_id": "22222222-2222-2222-2222-222222222222",
      "client_id": null,
      "checkout_by_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "team_id": "11111111-1111-1111-1111-111111111111",
      "total": 1500,
      "subtotal": 1500,
      "processing_fee": 0,
      "discount": null,
      "credits_applied": null,
      "coupon": null,
      "date_paid": "2026-02-10T14:30:00.000Z",
      "status": "PAID",
      "reference_number": "ORD-20260210-ABC123",
      "external_reference_number": null,
      "is_guest_order": false,
      "created_at": "2026-02-10T14:00:00.000Z",
      "updated_at": "2026-02-10T14:30:00.000Z",
      "deleted_at": null,
      "team": {
        "name": "Acme Corp"
      },
      "checkout_link": null,
      "line_items": [
        {
          "id": "55555555-5555-5555-5555-555555555555",
          "order_id": "44444444-4444-4444-4444-444444444444",
          "product_id": "33333333-3333-3333-3333-333333333333",
          "quantity": 1,
          "price": 1500,
          "is_add_on": false,
          "linked_order_line_item_id": null,
          "order_items": [
            {
              "id": "66666666-6666-6666-6666-666666666666",
              "campaign_id": null
            }
          ],
          "name": "Premium Tech Feature",
          "product_type_name": "Guest Post",
          "type_id": "tttttttt-tttt-tttt-tttt-tttttttttttt",
          "product_type_prefix": "guest_post",
          "outlet": {
            "logo": "https://cdn.presscart.com/logos/techdaily.png",
            "website_url": "https://techdaily.com"
          },
          "created_at": "2026-02-10T14:00:00.000Z",
          "updated_at": "2026-02-10T14:00:00.000Z",
          "deleted_at": null
        }
      ]
    }
  ],
  "total_records": 12,
  "total_pages": 2,
  "current_page": 1,
  "next_page": 2,
  "previous_page": null
}

Get order

GET /orders/{order_id}

Retrieve a single order by ID.

Scope: orders.read

Description: Returns a single order plus its line items with outlet and channel details. The response includes a checkout_link when the order status is not PAID (otherwise null).

Path parameters

ParameterTypeDescription
order_idstringUUID of the order

Request

curl "https://api.presscart.com/orders/44444444-4444-4444-4444-444444444444" \
  -H "Authorization: Bearer $PRESSCART_API_TOKEN"

Response

{
  "id": "44444444-4444-4444-4444-444444444444",
  "profile_id": "22222222-2222-2222-2222-222222222222",
  "client_id": null,
  "checkout_by_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "team_id": "11111111-1111-1111-1111-111111111111",
  "total": 1500,
  "subtotal": 1500,
  "processing_fee": 0,
  "discount": null,
  "credits_applied": null,
  "coupon": null,
  "date_paid": "2026-02-10T14:30:00.000Z",
  "status": "PAID",
  "reference_number": "ORD-20260210-ABC123",
  "external_reference_number": null,
  "is_guest_order": false,
  "created_at": "2026-02-10T14:00:00.000Z",
  "updated_at": "2026-02-10T14:30:00.000Z",
  "deleted_at": null,
  "name": "Acme Corp",
  "checkout_link": null,
  "line_items": [
    {
      "id": "55555555-5555-5555-5555-555555555555",
      "order_id": "44444444-4444-4444-4444-444444444444",
      "product_id": "33333333-3333-3333-3333-333333333333",
      "quantity": 1,
      "price": 1500,
      "is_add_on": false,
      "linked_order_line_item_id": null,
      "order_items": [
        {
          "id": "66666666-6666-6666-6666-666666666666",
          "campaign_id": null
        }
      ],
      "name": "Premium Tech Feature",
      "product_type_name": "Guest Post",
      "type_id": "tttttttt-tttt-tttt-tttt-tttttttttttt",
      "outlet": {
        "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
        "name": "TechDaily",
        "logo": "https://cdn.presscart.com/logos/techdaily.png",
        "website_url": "https://techdaily.com"
      },
      "includes": [
        {
          "channel_type": "NEWSLETTER",
          "placement_type": "MENTION"
        }
      ],
      "created_at": "2026-02-10T14:00:00.000Z",
      "updated_at": "2026-02-10T14:00:00.000Z",
      "deleted_at": null
    }
  ]
}

List order items

GET /order-items

List order items for your team.

Scope: orders.lists

Description: Returns order items for your team. API tokens are automatically limited to their own team. The internal_cost and reseller_price fields are nulled for API-token callers.

Parameters

ParameterTypeDescription
limitnumberNumber of records per page
pagenumberPage number
sort_bystringField to sort by
order_bystringSort direction (asc or desc)

Request

curl "https://api.presscart.com/order-items?limit=20" \
  -H "Authorization: Bearer $PRESSCART_API_TOKEN"

Response

{
  "records": [
    {
      "id": "55555555-5555-5555-5555-555555555555",
      "referrer_id": null,
      "referrer_team_id": null,
      "product_id": "33333333-3333-3333-3333-333333333333",
      "is_accounting_completed": false,
      "is_publisher_paid": false,
      "is_reseller_paid": false,
      "refund_required": false,
      "is_refunded": false,
      "refund_date": null,
      "refund_method": null,
      "refund_reference": null,
      "accounting_completion_date": null,
      "publisher_paid_date": null,
      "reseller_paid_date": null,
      "created_at": "2026-02-10T14:00:00.000Z",
      "updated_at": "2026-02-10T14:00:00.000Z",
      "deleted_at": null,
      "order_id": "44444444-4444-4444-4444-444444444444",
      "client_id": null,
      "date_paid": "2026-02-10T14:30:00.000Z",
      "sale_price": 1500,
      "product_name": "Premium Tech Feature",
      "product_price": 1500,
      "product_type": "guest_post",
      "article_id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "article": {
        "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
        "name": "Premium Tech Feature",
        "campaign": {
          "id": "66666666-6666-6666-6666-666666666666",
          "name": "Q2 Product Launch",
          "profile_id": "22222222-2222-2222-2222-222222222222"
        },
        "writer": {
          "id": "wwwwwwww-wwww-wwww-wwww-wwwwwwwwwwww",
          "first_name": "Jane",
          "last_name": "Smith"
        }
      },
      "internal_cost": null,
      "reseller_price": null,
      "client": {
        "first_name": "John",
        "last_name": "Doe"
      },
      "outlet": {
        "logo": "https://cdn.presscart.com/logos/techdaily.png"
      }
    }
  ],
  "total_records": 5,
  "total_pages": 1,
  "current_page": 1,
  "next_page": null,
  "previous_page": null
}

Create order

POST /orders/checkout

Create a new order.

Scope: orders.create

Description: Creates an order from line items and a profile ID. The profile must belong to the token's team.

Body

FieldTypeRequiredDescription
profile_idstringYesUUID of the profile placing the order
line_itemsarrayYesArray of line item objects
line_items[].product_idstringYesUUID of the product
line_items[].quantitynumberYesQuantity to order
line_items[].is_add_onbooleanYesWhether this is an add-on item
line_items[].linked_order_line_item_idstring | nullNoUUID of the parent line item for add-ons, or null
apply_creditsbooleanNoIgnored for API tokens. A token pays from Team Credits only when a person has given it a spend grant; otherwise credits are never applied and the order waits at its checkout_link.

Discounts are applied with a coupon, so a request that sends a non-zero discount is rejected with 422.

Headers

HeaderRequiredDescription
Idempotency-KeyNo1 to 255 printable ASCII characters with no spaces, unique for each order you intend to create. A UUID works well. Makes the request safe to retry; see below.

Retrying safely with Idempotency-Key

Send the same Idempotency-Key and the same body on every retry of one order, for example after a timeout or a dropped connection. The key is scoped to your team, so another team can use the same value without any effect on yours. Presscart keeps each key for at least 24 hours after the first request finishes. The key is tied to the order in the same database transaction that creates it, so once an order exists every retry with that key returns it, even if the first request failed or stopped after creating it. A first request that stopped before creating an order holds its key for at most 10 minutes, then frees it.

SituationResult
First request with the keyProcessed normally.
Same key and same body after the first request succeededThe original status and body are returned, with the response header Idempotent-Replayed: true. No second order is created.
Same key and a different body422 with code idempotency_key_reused. Nothing is created. Use a new key for a new order.
Same key while the first request is still running409 with code idempotency_key_in_flight. Wait a moment and retry with the same key.
The first request failed before creating an order (any 4xx or 5xx)The key is released, so you can fix the request and retry with the same key.
The first request created the order, then failedThe order is returned as it is now, with Idempotent-Replayed: true. Fields that changed since, such as status after payment, show their current values. No second order is created.
Key longer than 255 characters, or with spaces or non-ASCII characters400 with code idempotency_key_invalid.

Requests without the header behave exactly as before, so two identical requests create two orders. A replayed response is the same body you received the first time, including the same checkout_link. A response rebuilt after a failed first request shows the order as it is now. Neither contains payment secrets, which this endpoint never returns.

With a spend grant, an order is paid from the credit balance only. These extra responses can come back; see Agent spending:

  • 202 with status: "pending_approval" when the order would pass the token's monthly cap. Nothing was placed or charged; poll GET /orders/approvals/{approval_id}.
  • 402 with code: "INSUFFICIENT_CREDIT_BALANCE" when the balance does not cover the order. No card payment is started.
  • 503 with code: "APPROVAL_EMAIL_FAILED" when the approval email could not be sent, or code: "APPROVAL_EMAIL_PENDING" when a retry arrives while the first identical request is still sending it. Nothing was placed; retry shortly.

Resending a held cart returns the same pending approval, and a retry with the same Idempotency-Key replays the same 202. If its price changed since it was held and it still passes the cap, it is held again at the new price with a new approval email.

Response fields

FieldTypeDescription
checkout_linkstring | nullGuest checkout URL you can share with the customer so they can pay online

Request

curl -X POST "https://api.presscart.com/orders/checkout" \
  -H "Authorization: Bearer $PRESSCART_API_TOKEN" \
  -H "Idempotency-Key: 6f0c1d2e-3b4a-4c5d-8e9f-0a1b2c3d4e5f" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "22222222-2222-2222-2222-222222222222",
    "line_items": [
      {
        "product_id": "33333333-3333-3333-3333-333333333333",
        "quantity": 1,
        "is_add_on": false,
        "linked_order_line_item_id": null
      }
    ]
  }'

Response

{
  "id": "44444444-4444-4444-4444-444444444444",
  "profile_id": "22222222-2222-2222-2222-222222222222",
  "client_id": null,
  "checkout_by_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "team_id": "11111111-1111-1111-1111-111111111111",
  "total": 1500,
  "subtotal": 1500,
  "processing_fee": 0,
  "discount": null,
  "credits_applied": null,
  "coupon": null,
  "date_paid": null,
  "status": "CREATED",
  "reference_number": "ORD-20260210-ABC123",
  "external_reference_number": null,
  "is_guest_order": false,
  "created_at": "2026-02-10T14:00:00.000Z",
  "updated_at": "2026-02-10T14:00:00.000Z",
  "deleted_at": null,
  "checkout_link": "https://app.presscart.com/orders/checkout/ORD-20260210-ABC123",
  "line_items": [
    {
      "product_id": "33333333-3333-3333-3333-333333333333",
      "is_add_on": false,
      "price": 1500,
      "quantity": 1,
      "linked_order_line_item_id": null
    }
  ]
}

Products

Product details and marketplace listings.

Teams

Endpoints for viewing and updating API-token team details.

On this page

List orders
Parameters
Request
Response
Get order
Path parameters
Request
Response
List order items
Parameters
Request
Response
Create order
Body
Headers
Retrying safely with Idempotency-Key
Response fields
Request
Response