Create a sale/order (complimentary tickets and programmatic sales)

Minimum role: ADMIN. Active workspace via the X-Workspace-Id header.

Accepts Idempotency-Key: retrying with the same key returns the sale created on the first attempt (a 201 response with the Idempotent-Replay: true header) instead of issuing another one. Recommended for any client that retries on its own.

POST/sales

Authorization

AuthorizationAPI key · headerrequired

API key prefixed with Bearer . Alternative: the x-api-key header with the raw key. Available scopes: read and write (see /.well-known/oauth-protected-resource).

x-api-keyAPI key · headerrequired

Raw API key (without Bearer ), alternative to Authorization.

Header parameters

X-Workspace-Idstring

Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).

Idempotency-Keystring

Client-chosen idempotency key (max. 255 characters). Retrying with the SAME key returns the resource created by the first attempt instead of creating another one. Unique per workspace.

Request body

requiredapplication/json

buyerobjectrequired

Show properties

namestringrequired

min length 1

emailstring<email>required

matches ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

phonestring

min length 1

itemsobject[]required

min items 1

Show properties

Array of object

ticketTypeIdstringrequired

min length 1

quantityintegerrequired

min 1 · max 9007199254740991

seatsstring[]

channelstringrequired

default: "ADMIN"

Allowed:WEBMOBILEPOSADMIN

compbooleanrequired

default: false

notesstring

Responses

201

dataSaleDetailrequired

Show properties

idstringrequired

referencestringrequired

statusstringrequired

Allowed:PENDINGCONFIRMEDABANDONEDCANCELLEDREFUNDED

channelstringrequired

subtotalnumberrequired

discountAmountnumberrequired

serviceFeenumberrequired

ivanumberrequired

totalnumberrequired

currencystringrequired

buyerNamestringrequired

buyerEmailstringrequired

buyerPhonestring | nullrequired

Show properties

Any of:

string

string

null

null

buyerDocumentTypestring | nullrequired

Show properties

Any of:

string

string

null

null

buyerDocumentNumberstring | nullrequired

Show properties

Any of:

string

string

null

null

organizationIdstring | nullrequired

Show properties

Any of:

string

string

null

null

paymentProviderstring | nullrequired

Show properties

Any of:

string

string

null

null

paymentRefstring | nullrequired

Show properties

Any of:

string

string

null

null

confirmedAtstring | nullrequired

Show properties

Any of:

string

string

null

null

createdAtstringrequired

failureReasonstring | nullrequired

Show properties

Any of:

string

string

null

null

paymentStatusstring | nullrequired

Status of the latest payment event. Usually the payment gateway's RAW status in its own vocabulary. Values prefixed with FT_ come from FreeTicket, not the gateway: currently FT_SALE_APPROVED_POST_CONFIRM, which marks that the gateway re-notified an already-confirmed charge — this is how Bold reports its refunds. A CONFIRMED sale with this status may have money refunded that is not yet recorded.

Show properties

Any of:

string

string

null

null

declineCodestring | nullrequired

Show properties

Any of:

string

string

null

null

itemsSaleItem[]required

Show properties

Array of SaleItem

idstringrequired

ticketTypeIdstringrequired

quantityintegerrequired

min -9007199254740991 · max 9007199254740991

unitPricenumberrequired

subtotalnumberrequired

ticketCodestringrequired

checkedInAtstring | nullrequired

Show properties

Any of:

string

string

null

null

seatLabelstring | nullrequired

Show properties

Any of:

string

string

null

null

401

Missing or invalid credential.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

retryablebooleanrequired

detailsany

403

Insufficient role or resource not accessible.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

retryablebooleanrequired

detailsany

404

Resource does not exist or is out of scope.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

retryablebooleanrequired

detailsany

409

Conflict: the resource does not allow this operation in its current state.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

retryablebooleanrequired

detailsany

422

Request body/parameter validation failed.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

retryablebooleanrequired

detailsany

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

API keyRemember on this deviceInclude my values in samples

Parameters

X-Workspace-IdheaderActive workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).Idempotency-KeyheaderClient-chosen idempotency key (max. 255 characters). Retrying with the SAME key returns the resource created by the first attempt instead of creating another one. Unique per workspace.

Bodyapplication/json

Request body

Request

curl -X POST 'https://admin.appfreeticket.com/api/v1/sales' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "buyer": {
    "name": "string",
    "email": "user@example.com",
    "phone": "string"
  },
  "items": [
    {
      "ticketTypeId": "string",
      "quantity": 1,
      "seats": [
        "string"
      ]
    }
  ],
  "channel": "WEB",
  "comp": false,
  "notes": "string"
}'

const response = await fetch("https://admin.appfreeticket.com/api/v1/sales", {
  method: "POST",
  headers: {
    "Authorization": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: "{\n  \"buyer\": {\n    \"name\": \"string\",\n    \"email\": \"user@example.com\",\n    \"phone\": \"string\"\n  },\n  \"items\": [\n    {\n      \"ticketTypeId\": \"string\",\n      \"quantity\": 1,\n      \"seats\": [\n        \"string\"\n      ]\n    }\n  ],\n  \"channel\": \"WEB\",\n  \"comp\": false,\n  \"notes\": \"string\"\n}"
});

import requests

response = requests.post(
    "https://admin.appfreeticket.com/api/v1/sales",
    headers={
        "Authorization": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    data="{\n  \"buyer\": {\n    \"name\": \"string\",\n    \"email\": \"user@example.com\",\n    \"phone\": \"string\"\n  },\n  \"items\": [\n    {\n      \"ticketTypeId\": \"string\",\n      \"quantity\": 1,\n      \"seats\": [\n        \"string\"\n      ]\n    }\n  ],\n  \"channel\": \"WEB\",\n  \"comp\": false,\n  \"notes\": \"string\"\n}",
)

Response

{
  "data": {
    "id": "string",
    "reference": "string",
    "status": "PENDING",
    "channel": "string",
    "subtotal": 0,
    "discountAmount": 0,
    "serviceFee": 0,
    "iva": 0,
    "total": 0,
    "currency": "string",
    "buyerName": "string",
    "buyerEmail": "string",
    "buyerPhone": "string",
    "buyerDocumentType": "string",
    "buyerDocumentNumber": "string",
    "organizationId": "string",
    "paymentProvider": "string",
    "paymentRef": "string",
    "confirmedAt": "string",
    "createdAt": "string",
    "failureReason": "string",
    "paymentStatus": "string",
    "declineCode": "string",
    "items": [
      {
        "id": "string",
        "ticketTypeId": "string",
        "quantity": -9007199254740991,
        "unitPrice": 0,
        "subtotal": 0,
        "ticketCode": "string",
        "checkedInAt": "string",
        "seatLabel": "string"
      }
    ]
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": null
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": null
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": null
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": null
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": null
  }
}