Orders & Commissions API

Manage tracked conversions, line-item order details, commission review, approvals, bulk moderation, and CSV exports across all store locations.

Manage tracked conversions (orders), view commission statistics, approve or reject pending commissions, and export data.

Authentication

All endpoints require a Bearer access token with the appropriate scope. See Authentication.

Endpoints

List Orders — GET /v1/orders

Returns a paginated list of conversions with filtering, sorting, and search.

Query Parameters

Example

curl "https://api.heldsway.com/api/v1/orders?status=pending&sort=order_total&direction=desc&per_page=10" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "OK",
  "data": {
    "items": [
      {
        "id": 42,
        "order_id": "#135419",
        "affiliate": {
          "id": 7,
          "name": "Salman",
          "referral_code": "SALMAN2026"
        },
        "customer": {
          "name": "Geonwoo Park",
          "email": "geonwoo@example.com"
        },
        "subtotal": "70.00",
        "discount_applied": "0.00",
        "tax": "0.00",
        "order_total": "70.00",
        "commission_rate": "10.00",
        "commission_amount": "7.00",
        "currency": "USD",
        "location_id": "STORE-42",
        "location_name": "Downtown Store",
        "source_domain": "rentmy.com",
        "status": "pending",
        "converted_at": "2026-04-10T14:30:00.000000Z",
        "created_at": "2026-04-10T14:30:00.000000Z"
      },
      {
        "id": 41,
        "order_id": "#135380",
        "affiliate": null,
        "customer": null,
        "subtotal": "140.00",
        "discount_applied": "0.00",
        "tax": "0.00",
        "order_total": "140.00",
        "commission_rate": "0.00",
        "commission_amount": "0.00",
        "currency": "USD",
        "status": "approved",
        "converted_at": "2026-04-08T14:30:00.000000Z",
        "created_at": "2026-04-08T14:30:00.000000Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "per_page": 10,
      "total": 2,
      "last_page": 1
    }
  }
}

Response Fields

Get Order Stats — GET /v1/orders/stats

Returns aggregated summary statistics for the business’s affiliate-attributed orders. An order counts unless its status is cancelled — pending, approved, rejected and $0 orders all count. Optionally filter by date range. These are the same figures as the stat cards on the business panel’s Orders & Commissions page.

Query Parameters

Example

curl "https://api.heldsway.com/api/v1/orders/stats?from=2026-04-01&to=2026-04-15" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "OK",
  "data": {
    "total_orders": 2,
    "total_revenue": 210.00,
    "total_commission": 14.00,
    "pending_commission": 0.00,
    "approved_commission": 14.00
  }
}

Response Fields

Get Order Detail — GET /v1/orders/{id}

Returns the full detail for a single conversion, including line items and click attribution.

Path Parameters

Example

curl "https://api.heldsway.com/api/v1/orders/42" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 42,
    "order_id": "#135380",
    "affiliate": {
      "id": 7,
      "name": "Salman",
      "referral_code": "SALMAN2026",
      "commission_rate": "10.00"
    },
    "customer": {
      "name": "Jane Smith",
      "email": "jane@example.com"
    },
    "subtotal": "140.00",
    "discount_applied": "0.00",
    "tax": "0.00",
    "order_total": "140.00",
    "commission_rate": "10.00",
    "commission_amount": "14.00",
    "currency": "USD",
    "status": "approved",
    "line_items": [
      { "name": "Mountain Bike Rental", "quantity": 1, "price": "140.00" }
    ],
    "ip_address": "192.168.1.100",
    "click": {
      "id": 123,
      "referral_link_id": 45,
      "landing_page": "https://mountainthreads.example.com/bikes",
      "referrer": "https://instagram.com",
      "created_at": "2026-04-08T10:00:00.000000Z"
    },
    "converted_at": "2026-04-08T14:30:00.000000Z",
    "created_at": "2026-04-08T14:30:00.000000Z",
    "updated_at": "2026-04-08T15:00:00.000000Z"
  }
}

Additional Detail Fields

These fields appear only in the detail response (not in the list):

Error — HTTP 404

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Order not found."
  }
}

Approve Order — POST /v1/orders/{id}/approve

Transitions a pending conversion to approved status. The commission is considered owed once approved.

Path Parameters

Body Parameters

Example

curl -X POST "https://api.heldsway.com/api/v1/orders/42/approve" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Verified payment received" }'

Success Response — HTTP 200

{
  "success": true,
  "message": "Order #135419 approved.",
  "data": {
    "id": 42,
    "order_id": "#135419",
    "status": "approved",
    "commission_amount": "7.00",
    "updated_at": "2026-04-15T12:00:00.000000Z"
  }
}

Error — HTTP 409 (Invalid Status Transition)

{
  "success": false,
  "error": {
    "code": "INVALID_STATUS",
    "message": "Only pending conversions can be approved. Current status: approved"
  }
}

Error — HTTP 404

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Order not found."
  }
}

Reject Order — POST /v1/orders/{id}/reject

Transitions a pending conversion to rejected status. The commission is voided.

Path Parameters

Body Parameters

Example

curl -X POST "https://api.heldsway.com/api/v1/orders/42/reject" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Fraudulent order - chargeback received" }'

Success Response — HTTP 200

{
  "success": true,
  "message": "Order #135419 rejected.",
  "data": {
    "id": 42,
    "order_id": "#135419",
    "status": "rejected",
    "commission_amount": "7.00",
    "updated_at": "2026-04-15T12:00:00.000000Z"
  }
}

Error — HTTP 409 (Invalid Status Transition)

{
  "success": false,
  "error": {
    "code": "INVALID_STATUS",
    "message": "Only pending conversions can be rejected. Current status: approved"
  }
}

Bulk Approve — POST /v1/orders/bulk-approve

Approves multiple pending conversions in a single request. Non-pending conversions are silently skipped.

Body Parameters

Example

curl -X POST "https://api.heldsway.com/api/v1/orders/bulk-approve" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [42, 43, 44, 45, 46] }'

Success Response — HTTP 200

{
  "success": true,
  "message": "3 order(s) approved.",
  "data": {
    "approved_count": 3,
    "requested_count": 5,
    "skipped_count": 2
  }
}

Response Fields

Error — HTTP 422

BulkOrderActionApiRequest rejects the body before the controller runs, so the response is Laravel’s standard validation body (see Error Reference → Validation Errors (422)):

{
  "message": "The ids field is required.",
  "errors": {
    "ids": ["The ids field is required."]
  }
}

Bulk Reject — POST /v1/orders/bulk-reject

Rejects multiple pending conversions in a single request. Non-pending conversions are silently skipped.

Body Parameters

Example

curl -X POST "https://api.heldsway.com/api/v1/orders/bulk-reject" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [47, 48], "reason": "Duplicate orders from same session" }'

Success Response — HTTP 200

{
  "success": true,
  "message": "2 order(s) rejected.",
  "data": {
    "rejected_count": 2,
    "requested_count": 2,
    "skipped_count": 0
  }
}

Response Fields

Export Orders — GET /v1/orders/export

Downloads all matching conversions as a CSV file. Same filters as the list endpoint but without pagination — returns all matching records up to 10,000 rows.

Query Parameters

Example

curl "https://api.heldsway.com/api/v1/orders/export?status=approved&from=2026-04-01" \
  -H "Authorization: Bearer <access_token>" \
  -o orders-export.csv

Success Response — HTTP 200

Content-Type: text/csv Content-Disposition: attachment; filename="orders-export-2026-04-15.csv"

Order ID,Affiliate Name,Affiliate Code,Subtotal,Discount,Tax,Order Total,Commission Rate (%),Commission Amount,Currency,Status,Customer Email,Converted At
#135380,Salman,SALMAN2026,140.00,0.00,0.00,140.00,10.00,14.00,USD,approved,jane@example.com,2026-04-08 14:30:00
#135419,,,70.00,0.00,0.00,70.00,0.00,0.00,USD,pending,geonwoo@example.com,2026-04-10 14:30:00

CSV Columns

Conversion Status Workflow

  ┌─────────┐
  │ pending  │ ← initial state (from SDK tracking)
  └────┬─────┘
       │
  ┌────┴────┐
  ▼         ▼
┌─────────┐ ┌──────────┐
│ approved│ │ rejected │
└─────────┘ └──────────┘

  ┌───────────┐
  │ cancelled │ ← set by system (order cancellation)
  └───────────┘

• Only pending conversions can be approved or rejected via the API.
• Attempting to approve/reject a non-pending conversion returns HTTP 409.
• The cancelled status is set by the system when an order is cancelled — it is not available as an API action.

Error Reference

Rate Limiting

Exceeding the limit returns HTTP 429 Too Many Requests with error code RATE_LIMIT_EXCEEDED.