TicketSpice MCP by usefulapi

List the account's TicketSpice forms (ticketed events / order pages): id, name, status (open, closed, scheduled or archived), created and updated dates. Use the form ids to filter orders, tickets and transactions. GET /forms.

{
  "type": "object",
  "properties": {
    "created_after": {
      "description": "Only records created after this time.",
      "type": "string"
    },
    "created_before": {
      "description": "Only records created before this time.",
      "type": "string"
    },
    "updated_after": {
      "description": "Only records updated after this time.",
      "type": "string"
    },
    "updated_before": {
      "description": "Only records updated before this time.",
      "type": "string"
    },
    "limit": {
      "description": "Results per page, 1-50 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "starting_after": {
      "description": "Cursor: pass the previous reply's next_starting_after to get the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "sort": {
      "description": "Sort by id: asc or desc (the vendor default applies when omitted).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One form by id: name, status, accounting reference, time zone and its field layout. GET /forms/{id}.

{
  "type": "object",
  "properties": {
    "form_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "TicketSpice form id (from ticketspice_list_forms)."
    }
  },
  "required": [
    "form_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Inventory items of a form (limited-quantity items): path, name, sold and remaining quantity. GET /forms/{id}/inventory.

{
  "type": "object",
  "properties": {
    "form_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "TicketSpice form id."
    }
  },
  "required": [
    "form_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List orders (one per checkout): order number, buyer billing name and address, form, total, currency and status, newest or oldest first. Filter by event (form), status, buyer email, customer id, order number or dates. GET /search/orders.

{
  "type": "object",
  "properties": {
    "form_id": {
      "description": "Only orders of this form.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "status": {
      "description": "Order status string as the vendor returns it (for example \"completed\" or \"active\").",
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "email": {
      "description": "Only orders placed with this email address.",
      "type": "string",
      "minLength": 3,
      "maxLength": 254
    },
    "customer_id": {
      "description": "Only orders of this customer (buyer) id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "order_number": {
      "description": "Only the order with this order number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "created_after": {
      "description": "Only records created after this time.",
      "type": "string"
    },
    "created_before": {
      "description": "Only records created before this time.",
      "type": "string"
    },
    "updated_after": {
      "description": "Only records updated after this time.",
      "type": "string"
    },
    "updated_before": {
      "description": "Only records updated before this time.",
      "type": "string"
    },
    "limit": {
      "description": "Results per page, 1-50 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "starting_after": {
      "description": "Cursor: pass the previous reply's next_starting_after to get the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "sort": {
      "description": "Sort by id: asc or desc (the vendor default applies when omitted).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One order by id with the buyer's billing details, event, totals and status. Set include_tickets to embed the order's tickets and include_transactions its payments (charges and refunds). GET /search/orders/{id}.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "TicketSpice order id (from ticketspice_list_orders)."
    },
    "include_tickets": {
      "description": "Also return the order's tickets.",
      "type": "boolean"
    },
    "include_transactions": {
      "description": "Also return the order's transactions.",
      "type": "boolean"
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List payment transactions (money movements): amount, currency, type (charge, refund, voucher), payment method, masked card, status, form and buyer email. Filter by type, method, form, order, donor or dates. GET /search/transactions.

{
  "type": "object",
  "properties": {
    "form_id": {
      "description": "Only transactions of this form.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "type": {
      "description": "Transaction type.",
      "type": "string",
      "enum": [
        "charge",
        "refund",
        "voucher",
        "cash",
        "preauth",
        "chargeback"
      ]
    },
    "payment_method": {
      "description": "Payment method.",
      "type": "string",
      "enum": [
        "card",
        "check",
        "offline"
      ]
    },
    "status": {
      "description": "Transaction status string as the vendor returns it (for example \"completed\" or \"active\").",
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "order_id": {
      "description": "Only transactions of this order id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "customer_id": {
      "description": "Only transactions of this customer (buyer) id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "email": {
      "description": "Only transactions of orders placed with this email.",
      "type": "string",
      "minLength": 3,
      "maxLength": 254
    },
    "order_number": {
      "description": "Only transactions of this order number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "reference": {
      "description": "Only the transaction with this payment reference (txReference).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "created_after": {
      "description": "Only records created after this time.",
      "type": "string"
    },
    "created_before": {
      "description": "Only records created before this time.",
      "type": "string"
    },
    "updated_after": {
      "description": "Only records updated after this time.",
      "type": "string"
    },
    "updated_before": {
      "description": "Only records updated before this time.",
      "type": "string"
    },
    "limit": {
      "description": "Results per page, 1-50 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "starting_after": {
      "description": "Cursor: pass the previous reply's next_starting_after to get the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "sort": {
      "description": "Sort by id: asc or desc (the vendor default applies when omitted).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One transaction by id: amounts, type, payment method, masked card, gateway message and status. GET /search/transactions/{id}.

{
  "type": "object",
  "properties": {
    "transaction_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "TicketSpice transaction id (from ticketspice_list_transactions)."
    }
  },
  "required": [
    "transaction_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List sold tickets (one record per ticket): id, buyer billing name, event, ticket level, amount, fee, total, status, scan count and last scan time, event date. Filter by event (form), status, order, buyer email, customer id or dates. Use it for attendee lists and check-in status. GET /search/tickets.

{
  "type": "object",
  "properties": {
    "form_id": {
      "description": "Only tickets of this event (form) id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "status": {
      "description": "Ticket status string as the vendor returns it (for example \"completed\" or \"active\").",
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "order_id": {
      "description": "Only tickets of this order id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "order_display_id": {
      "description": "Only tickets of the order with this customer-facing order display id.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "customer_id": {
      "description": "Only tickets of this customer id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "email": {
      "description": "Only tickets of orders placed with this email address.",
      "type": "string",
      "minLength": 3,
      "maxLength": 254
    },
    "order_number": {
      "description": "Only tickets of this order number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "created_after": {
      "description": "Only records created after this time.",
      "type": "string"
    },
    "created_before": {
      "description": "Only records created before this time.",
      "type": "string"
    },
    "updated_after": {
      "description": "Only records updated after this time.",
      "type": "string"
    },
    "updated_before": {
      "description": "Only records updated before this time.",
      "type": "string"
    },
    "limit": {
      "description": "Results per page, 1-50 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "starting_after": {
      "description": "Cursor: pass the previous reply's next_starting_after to get the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "sort": {
      "description": "Sort by id: asc or desc (the vendor default applies when omitted).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One ticket by id: buyer, event, level, amount, fee, total, status, scan count, last scan time and the buyer's form answers. GET /search/tickets/{id}.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "TicketSpice ticket id (from ticketspice_list_tickets)."
    }
  },
  "required": [
    "ticket_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List customer records (buyers): id, email, billing name and address, total spent, created and updated dates. Filter by email or dates. New customers can take up to 5 minutes to appear. GET /search/customers.

{
  "type": "object",
  "properties": {
    "email": {
      "description": "Only the customer with this email address.",
      "type": "string",
      "minLength": 3,
      "maxLength": 254
    },
    "created_after": {
      "description": "Only records created after this time.",
      "type": "string"
    },
    "created_before": {
      "description": "Only records created before this time.",
      "type": "string"
    },
    "updated_after": {
      "description": "Only records updated after this time.",
      "type": "string"
    },
    "updated_before": {
      "description": "Only records updated before this time.",
      "type": "string"
    },
    "limit": {
      "description": "Results per page, 1-50 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "starting_after": {
      "description": "Cursor: pass the previous reply's next_starting_after to get the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "sort": {
      "description": "Sort by id: asc or desc (the vendor default applies when omitted).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One customer record by id: email, billing details and total of the customer's transactions. GET /search/customers/{id}.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "TicketSpice customer id (from ticketspice_list_customers, or an order's customerId)."
    }
  },
  "required": [
    "customer_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List TicketSpice coupons: account-wide ones, or only those of one form when form_id is given. Shows discounts, codes, availability, redeemed count and expiry. GET /coupons/global or /coupons/forms/{id}.

{
  "type": "object",
  "properties": {
    "form_id": {
      "description": "Only coupons of this form; omit for the account-wide (global) coupons.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "code": {
      "description": "Only global coupons with this code (ignored with form_id).",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "limit": {
      "description": "Results per page, 1-50 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "starting_after": {
      "description": "Cursor: pass the previous reply's next_starting_after to get the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "sort": {
      "description": "Sort by id: asc or desc (the vendor default applies when omitted).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One coupon by id with its discounts, codes, availability and redeemed counts. GET /coupons/{id}.

{
  "type": "object",
  "properties": {
    "coupon_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "TicketSpice coupon id (from ticketspice_list_coupons)."
    }
  },
  "required": [
    "coupon_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create a discount coupon in the live TicketSpice account (it can be redeemed by ticket buyers right away). One discount (fixed amount or percent) and one or more codes; optionally limited to one form, to a number of uses, and to an expiry date. Not idempotent: calling it twice creates two coupons. POST /coupons.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Internal coupon name."
    },
    "codes": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 100
      },
      "description": "One or more redeemable codes."
    },
    "discount_value": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1000000,
      "description": "Discount amount: currency units for a fixed discount, percent (1-100) for a percent discount."
    },
    "discount_type": {
      "type": "string",
      "enum": [
        "fixed",
        "percent"
      ],
      "description": "fixed (a currency amount) or percent."
    },
    "currency": {
      "description": "Currency code, default USD.",
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "available": {
      "description": "How many times the coupon can be used; -1 = unlimited (default).",
      "type": "integer",
      "minimum": -1,
      "maximum": 1000000
    },
    "form_id": {
      "description": "Restrict the coupon to this form; omit for all forms.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "per_ticket": {
      "description": "Apply the discount to each ticket instead of once per order (default false).",
      "type": "boolean"
    },
    "expires": {
      "description": "When the coupon expires; omit for no expiry.",
      "type": "string"
    }
  },
  "required": [
    "name",
    "codes",
    "discount_value",
    "discount_type"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: permanently delete a coupon from the live TicketSpice account; its codes stop working immediately and this cannot be undone. Show the coupon (ticketspice_get_coupon) and get the user's approval first, then call with confirm: true. GET /coupons/{id}, then DELETE /coupons/{id}.

{
  "type": "object",
  "properties": {
    "coupon_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "TicketSpice coupon id to delete."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: the user approved permanently deleting this coupon."
    }
  },
  "required": [
    "coupon_id",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}