Gift Up! MCP by usefulapi

The Gift Up account this API key belongs to: id, name, currency, whether onboarding is complete and whether the checkout is live. GET /company.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List gift cards with balance, status flags (canBeRedeemed, hasExpired, notYetValid, isVoided), title, recipient, expiry and the order they came from. Codes are MASKED (at least 6 characters stay hidden); to see one card in full (code and ledger) use giftup_get_gift_card with its code. Filter by state, creation/update time, order, SKU, recipient/purchaser email or payment transaction id. GET /gift-cards.

{
  "type": "object",
  "properties": {
    "status": {
      "description": "Only gift cards in this state.",
      "type": "string",
      "enum": [
        "active",
        "expired",
        "redeemed",
        "voided"
      ]
    },
    "created_on_or_after": {
      "description": "Only gift cards created on or after this time (UTC).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:?\\d{2})?)?$"
    },
    "updated_on_or_after": {
      "description": "Only gift cards updated on or after this time (UTC).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:?\\d{2})?)?$"
    },
    "order_id": {
      "description": "Only gift cards of this order id.",
      "type": "string",
      "pattern": "^[A-Za-z0-9-]{1,64}$"
    },
    "sku": {
      "description": "Only gift cards with this private SKU.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "recipient_email": {
      "description": "Only gift cards sent to this recipient email address.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "purchaser_email": {
      "description": "Only gift cards bought by this purchaser email address.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "payment_transaction_id": {
      "description": "Only gift cards whose payment-provider transaction id matches.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Results to skip (default 0). Pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    },
    "test_mode": {
      "description": "Read the account's test data instead of live data (sends x-giftup-testmode: true). Default false.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One gift card by its code: balance (remainingValue / remainingUnits), status flags, expiry, recipient, order, fulfilment and the full ledger of events (created, redeemed, topped up, voided). Returns the code in full because you asked for this card by code; do not repeat it elsewhere. Read-only: it never redeems or changes the card. GET /gift-cards/{code}.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "The gift card code."
    },
    "test_mode": {
      "description": "Read the account's test data instead of live data (sends x-giftup-testmode: true). Default false.",
      "type": "boolean"
    }
  },
  "required": [
    "code"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List orders (the purchases that created gift cards), newest first: order number, purchaser, revenue, tip, fees, discount, applied promotions, source, notes, metadata and payment provider. Filter by creation time, purchaser email or source. GET /orders.

{
  "type": "object",
  "properties": {
    "created_on_or_after": {
      "description": "Only orders created on or after this time (UTC).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:?\\d{2})?)?$"
    },
    "purchaser_email": {
      "description": "Only orders by this purchaser email address.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "source": {
      "description": "Only orders from this source.",
      "type": "string",
      "enum": [
        "API",
        "Checkout",
        "Dashboard",
        "Import",
        "Square",
        "Vend",
        "External"
      ]
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Results to skip (default 0). Pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    },
    "test_mode": {
      "description": "Read the account's test data instead of live data (sends x-giftup-testmode: true). Default false.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One order by id: totals, purchaser, promotions, custom fields, sales taxes, notes, metadata and payment provider. GET /orders/{id}.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9-]{1,64}$",
      "description": "The order id (a GUID, from giftup_list_orders)."
    },
    "test_mode": {
      "description": "Read the account's test data instead of live data (sends x-giftup-testmode: true). Default false.",
      "type": "boolean"
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the gift card products on sale (items): name, price, value, price type, availability window, group, stock level, per-order limit, SKU and terms. Pre-generated codes are reduced to a count and masked tails. Optionally only one group. GET /items.

{
  "type": "object",
  "properties": {
    "group_id": {
      "description": "Only items in this item group id.",
      "type": "string",
      "pattern": "^[A-Za-z0-9-]{1,64}$"
    },
    "test_mode": {
      "description": "Read the account's test data instead of live data (sends x-giftup-testmode: true). Default false.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One item (gift card product) by id. Pre-generated codes are reduced to a count and masked tails. GET /items/{id}.

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9-]{1,64}$",
      "description": "The item id (a GUID, from giftup_list_items)."
    },
    "test_mode": {
      "description": "Read the account's test data instead of live data (sends x-giftup-testmode: true). Default false.",
      "type": "boolean"
    }
  },
  "required": [
    "item_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List item groups (the sections that organize items in the checkout): id, name, description, sort order, auto-expand. GET /groups.

{
  "type": "object",
  "properties": {
    "test_mode": {
      "description": "Read the account's test data instead of live data (sends x-giftup-testmode: true). Default false.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One item group by id. GET /groups/{id}.

{
  "type": "object",
  "properties": {
    "group_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9-]{1,64}$",
      "description": "The item group id (a GUID, from giftup_list_item_groups)."
    },
    "test_mode": {
      "description": "Read the account's test data instead of live data (sends x-giftup-testmode: true). Default false.",
      "type": "boolean"
    }
  },
  "required": [
    "group_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the locations (stores) of the account; their ids filter and label report transactions. GET /locations.

{
  "type": "object",
  "properties": {
    "test_mode": {
      "description": "Read the account's test data instead of live data (sends x-giftup-testmode: true). Default false.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List promotions (checkout discounts and bonus credit): name, published/stopped dates, benefits (percentage and fixed discounts, extra credit), usage counts and revenue, limitations and triggers (items, groups, spend and quantity thresholds, promo code). Read-only. GET /promotions.

{
  "type": "object",
  "properties": {
    "test_mode": {
      "description": "Read the account's test data instead of live data (sends x-giftup-testmode: true). Default false.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The immutable financial transaction log: OrderPlaced (income, fees, tip), GiftCardCreated, CreditAdded, Redeemed, Expired, Unexpired, Voided, Reactivated, with who, where, reason, Gift Up fee and the value change. Gift card codes are MASKED (at least 6 characters stay hidden). Filter by time range, event type, user email, location id or one gift card code. GET /reports/transactions.

{
  "type": "object",
  "properties": {
    "event_occurred_on_or_after": {
      "description": "Only events on or after this time (UTC).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:?\\d{2})?)?$"
    },
    "event_occurred_on_or_before": {
      "description": "Only events on or before this time (UTC).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:?\\d{2})?)?$"
    },
    "events": {
      "description": "Only these event types.",
      "minItems": 1,
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "OrderPlaced",
          "GiftCardCreated",
          "CreditAdded",
          "Redeemed",
          "Expired",
          "Unexpired",
          "Voided",
          "Reactivated"
        ]
      }
    },
    "users": {
      "description": "Only events generated by these user email addresses.",
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    },
    "locations": {
      "description": "Only events at these location ids (see giftup_list_locations).",
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9-]{1,64}$",
        "description": "The id (a GUID)."
      }
    },
    "code": {
      "description": "Only events of the gift card with this code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Results to skip (default 0). Pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    },
    "test_mode": {
      "description": "Read the account's test data instead of live data (sends x-giftup-testmode: true). Default false.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One report transaction by id. The gift card code inside is MASKED (at least 6 characters stay hidden). GET /reports/transactions/{id}.

{
  "type": "object",
  "properties": {
    "transaction_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9-]{1,64}$",
      "description": "The transaction id (a GUID, from giftup_list_transactions)."
    },
    "test_mode": {
      "description": "Read the account's test data instead of live data (sends x-giftup-testmode: true). Default false.",
      "type": "boolean"
    }
  },
  "required": [
    "transaction_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}