Create an order

Create a cart and hold places. No money moves until you pay it.

POST /orders

Create an order

cURL

curl --request POST \
  --url https://connect.laces.run/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "event_id": "q3Zk9mVx",
  "lines": [
    {
      "ticket_type_id": "tt_10k",
      "quantity": 1,
      "participants": [
        {
          "distance_km": 10
        }
      ]
    }
  ],
  "buyer_name": "Amina Nakato",
  "buyer_email": "[e-mail]",
  "buyer_phone": "0763494235",
  "payment_method": "momo",
  "waiver_accepted": true,
  "waiver_version": "2026-09-01",
  "custom_fields": {
    "kit_size": "M"
  },
  "partner_reference": "cart-8841"
}
'

200

Example

{
  "code": 200,
  "message": "Cart already created (idempotent replay)",
  "data": {
    "order": {
      "id": "Hk2mQ8vR",
      "order_code": "LC-7K2M9X",
      "event_id": "q3Zk9mVx",
      "status": "cart",
      "currency": "UGX",
      "subtotal": 50000,
      "discount_total": 0,
      "donation_total": 0,
      "laces_fee": 2400,
      "total": 52400,
      "failure_kind": null,
      "ticket_count": 1,
      "buyer": {
        "name": "Amina Nakato",
        "email": "[e-mail]",
        "phone": "[phone]"
      },
      "attribution": {
        "channel": "partner_api",
        "api_client_id": "LCSCLI-EXAMPLECLNT2345EXAMP",
        "checkout_session_id": null,
        "partner_reference": "cart-8841"
      },
      "hold_expires_at": "2026-10-09T08:29:03.000Z",
      "created_at": "2026-10-09T08:14:03.000Z"
    },
    "checkout_lines": [
      {
        "label": "Subtotal",
        "amount": 50000
      },
      {
        "label": "Laces Service Fee",
        "amount": 2400
      },
      {
        "label": "Total",
        "amount": 52400
      }
    ],
    "is_free": false,
    "is_test_mode": false,
    "fee_rate": {
      "flat_fee": 0,
      "percent_fee": 0,
      "currency": "UGX",
      "payment_method": "momo"
    },
    "registrations": [
      {
        "id": "rg_5TfK2",
        "ticket_type_id": "tt_10k",
        "distance_km": 10,
        "status": "pending"
      }
    ],
    "event_name": "Kampala City 10K",
    "event_when_label": "Sun 15 Nov 2026, 7:00 AM"
  }
}

Authorizations

bearerAuthoauth2

Authorization · string · header · required

A token from POST /oauth/token, valid 1 hour. Paste it as LCSTOK-…-X (without the word Bearer).

Headers

Idempotency-Key · string · required

Any unique string you generate (a UUID is ideal), stored with your cart and reused on every retry of the same action. Scoped to your API client.

Maximum string length: 255

Body

application/json

event_id · string · required

Must be your organization's event.

Example:

"q3Zk9mVx"

lines · object[] · required

Minimum array length: 1

Show child attributes

buyer_name · string · required

Example:

"Amina Nakato"

buyer_email · string<email> · required

Receipts and tickets go here.

Example:

"[e-mail]"

buyer_phone · string · required

The buyer's phone number. Returned in E.164 (+2567…) in every order read.

Example:

"0763494235"

payment_method · enum<string> · default: momo

Sets the price. momo (default) is MTN Mobile Money only; airtel is Airtel Money only. Choose from the buyer's number: the pay call answers 409 reprice_required when the number's network does not match. Use only methods in the event's payment_methods: card is refused with 409 payment_method_unavailable until card is available (coming soon).

Available options: momo, card, airtel

waiver_accepted · boolean

Required (true) when the event's waiver_required is true.

waiver_version · string

Required when waiver_required; must equal the event's current waiver_version.

custom_fields · object

Answers to additional_questions, keyed by key.

discount_code · string

donation_amount · integer

Minor units.

Required range: x >= 0

partner_reference · string

Your own reference. Echoed back as attribution.partner_reference in order reads and webhooks.

Maximum string length: 128

referral_code · string

Optional referral code.

note · string

Optional note on the order.

guardian · object

Parent or guardian details, when the event requires them for minors.

buyer · object

Optional extra buyer fields, stored with the order.

Response

200

application/json

Idempotent replay of an earlier request with the same key.

code · integer · required

HTTP status, repeated in the body.

Example:

200

message · string · required

Example:

"Cart already created (idempotent replay)"

data · object · required

Show child attributes