FlintflintDocs

Customer account

/v1/me is the buyer's own view of their commerce data. Every endpoint here is authorized by a customer session secret, and the identity in that credential decides whose data is returned.

There is no customer_id argument anywhere in this namespace. A customer_id in the query string, or nested anywhere in the request body, is rejected with ME_CUSTOMER_ID_FORBIDDEN rather than ignored. A resource that exists but belongs to another buyer returns 404, not 403, so the namespace does not confirm that someone else's order ID is real.

Use this when you build your own account UI. Flint keeps enforcing ownership on the server, so a bug in your front end cannot show one buyer another buyer's order.

What the buyer can do#

JobEndpoints
Profile and emailGET/PATCH /v1/me, email change request and confirm
OrdersOrders, order activity, receipt resend
MoneyPayments, refunds
DeliveryFulfillments, shipments, packages
InvoicesList, get, PDF, and a checkout session to pay one
SubscriptionsList, get, pause, resume, cancel, reactivate, change payment method
Saved payment methodsList, add, remove, set default
AddressesList, create, get, update, delete, set default
ReturnsEligibility check, create, get, cancel, resolution preview, resolution, resolution checkout session
Account closureDeletion request and status

A narrowed projection, not an alias#

These are not the merchant endpoints with a filter applied. Reads are trimmed to what a buyer should see, and writes are limited to what a buyer should be able to do to their own account.

Returns are the clearest case: a Return read through a customer session carries a narrower supported_actions and completion_blockers than the same Return read with a merchant key, because a buyer cannot receive, inspect, or approve their own Return. See self-serve Returns.

expand is not available here.

Writes that move money#

Paying an invoice and paying a Return resolution both go through a checkout session rather than a direct charge. The buyer's own account never carries payment authority, and Flint's hosted payment surface handles the card. This is the same for a merchant-hosted account as for Flint's.

Endpoints

Get the current buyer profile#

GET/v1/meRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Returns a single customer by ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDANGLING_EXPANSION_REFERENCEEXPANSION_DEPENDENCY_UNAVAILABLEEXPANSION_RESOLUTION_FAILEDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

Update the current buyer profile#

PATCH/v1/meIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. Updates the current buyer's name or phone. Manage billing and shipping addresses through /v1/me/addresses.

Request body
namestring
phonestring
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "Ada Lovelace",
    "phone": "+14155550123"
  }'
JSON
{
  "data": {
    "customer_id": "cus_123",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "metadata": {
      "crm_id": "crm_123"
    },
    "merchant_id": "mer_123",
    "billing_address": {
      "line1": "123 Main St",
      "country": "US",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001"
    },
    "phone": "+14155552671",
    "tax_exempt": true,
    "group_id": "vip",
    "is_verified": true,
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List the current buyer's addresses#

GET/v1/me/addressesRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Lists the customer's saved addresses with billing and shipping default flags.

Query parameters
page_sizeinteger

Number of addresses to return.

page_tokenstring

Opaque token returned by the previous page.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/me/addresses \
  -H "Authorization: Bearer YOUR_API_KEY"

Create an address for the current buyer#

POST/v1/me/addressesIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Creates a stable saved address. The first address becomes both the billing and shipping default. A saved default becomes the customer's effective address for the corresponding role.

Request body
addressobjectrequired
is_default_billingboolean
is_default_shippingboolean
labelstring
phonestring
recipient_namestringrequired
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/me/addresses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "address": {
      "city": "",
      "country": "US",
      "line1": "",
      "postal_code": "",
      "state": ""
    },
    "recipient_name": ""
  }'

Get one of the current buyer's addresses#

GET/v1/me/addresses/{customer_address_id}Requires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Returns one saved address owned by the customer.

Path parameters
customer_address_idstringrequired

Flint customer address ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/me/addresses/{customer_address_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Update one of the current buyer's addresses#

PATCH/v1/me/addresses/{customer_address_id}IdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Applies a sparse update to a saved address. Updating a default address also updates the customer's effective address for that role.

Path parameters
customer_address_idstringrequired

Flint customer address ID.

Request body
addressobject
labelstring
phonestring
recipient_namestring
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X PATCH https://api.withflintpay.com/v1/me/addresses/{customer_address_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "address": {
      "city": "",
      "country": "US",
      "line1": "",
      "postal_code": "",
      "state": ""
    },
    "label": "",
    "phone": "",
    "recipient_name": ""
  }'

Delete one of the current buyer's addresses#

DELETE/v1/me/addresses/{customer_address_id}IdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Deletes a saved address and moves any default designation to the newest remaining address.

Path parameters
customer_address_idstringrequired

Flint customer address ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X DELETE https://api.withflintpay.com/v1/me/addresses/{customer_address_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Set a default address for the current buyer#

POST/v1/me/addresses/{customer_address_id}/set-defaultIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Sets the address as the billing default, shipping default, or both and makes it the customer's effective address for each selected role.

Path parameters
customer_address_idstringrequired

Flint customer address ID.

Request body
default_forenumrequired
billingshippingboth
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/me/addresses/{customer_address_id}/set-default \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "default_for": "billing"
  }'

Request deletion of the current buyer's account#

POST/v1/me/deletion-requestsIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Creates or returns the pending tracked deletion request. Required commerce records are retained until the deletion workflow resolves their legal retention requirements.

Response · 202
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/me/deletion-requests \
  -H "Authorization: Bearer YOUR_API_KEY"

Get the current buyer's deletion request#

GET/v1/me/deletion-requests/{customer_deletion_request_id}Requires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Returns the current status of a tracked deletion request.

Path parameters
customer_deletion_request_idstringrequired

Flint customer deletion request ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/me/deletion-requests/{customer_deletion_request_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Request an email change#

POST/v1/me/email-change-requestsIdempotentRequires CustomerSessionBearer

Sends short-lived confirmation codes to the current and new email addresses. If the account has no current email, only the new address must be confirmed. The customer email does not change until confirmation succeeds.

Request body
new_emailstringrequired
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDCUSTOMER_EMAIL_ALREADY_USEDEMAIL_CHANGE_DELIVERY_FAILEDEMAIL_CHANGE_RATE_LIMITEDINSUFFICIENT_SCOPEINVALID_CUSTOMER_ACCOUNT_REQUESTINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/me/email-change-requests \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "new_email": ""
  }'

Confirm an email change#

POST/v1/me/email-change-requests/{email_change_request_id}/confirmIdempotentRequires CustomerSessionBearer

Confirms possession of the current and new email addresses, then atomically updates the customer account in the selected merchant environment. Omit current_email_code only when current_email_confirmation_required is false.

Path parameters
email_change_request_idstringrequired

Flint email change request ID.

Request body
current_email_codestring
new_email_codestringrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/me/email-change-requests/{email_change_request_id}/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "new_email_code": ""
  }'

List the current buyer's fulfillments#

GET/v1/me/fulfillmentsRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Returns fulfillments for operational queue and order-detail views. Results default to newest created first.

Query parameters
order_idstring

Filter by order ID.

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

external_reference_idstring

Exact-match filter on the caller-owned external reference ID.

querystring

Search across fulfillment_id and external_reference_id.

statusenum

Filter by current public fulfillment status.

pendingin_progressreadycompletedcanceledfailedscheduledpreparingpickedpackeddispatched
typeenum

Filter by fulfillment type.

shipmentpickuplocal_deliverydigitalservice
location_idstring

Filter by assigned Location ID.

created_afterstring

Lower bound for created_at.

created_beforestring

Upper bound for created_at.

updated_afterstring

Lower bound for updated_at.

updated_beforestring

Upper bound for updated_at.

sort_directionenum

Sort direction for created_at. Defaults to desc.

ascdesc
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDDANGLING_EXPANSION_REFERENCEEXPANSION_DEPENDENCY_UNAVAILABLEEXPANSION_RESOLUTION_FAILEDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/me/fulfillments \
  -H "Authorization: Bearer YOUR_API_KEY"

List the current buyer's invoices#

GET/v1/me/invoicesRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Returns a paginated list of invoices for the authenticated merchant.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

statusenum

Filter by invoice status. Repeat the parameter or pass comma-separated values to match multiple statuses.

draftopenpartially_paidpaidvoid
order_idstring

Filter by Flint order ID.

external_reference_idstring

Exact-match filter on the caller-owned external reference ID.

created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

due_afterstring

RFC3339 lower bound for due_at.

due_beforestring

RFC3339 upper bound for due_at.

is_overdueboolean

Filter by whether the invoice is overdue.

has_amount_dueboolean

Filter by whether the invoice has a remaining amount due.

sort_byenum

Sort field.

created_atupdated_atdue_atinvoice_numberoutstanding_money
sort_directionenum

Sort direction.

ascdesc
querystring

Search across invoice_id, invoice_number, external_reference_id, recipient_email, and reference.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/me/invoices \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "invoice_id": "inv_01J00000000000000000000000",
      "merchant_id": "mer_01J00000000000000000000000",
      "order_id": "ord_01J00000000000000000000000",
      "customer_id": "cus_01J00000000000000000000000",
      "invoice_number": "1042",
      "status": "open",
      "refund_status": "none",
      "collection_block_status": "",
      "due_at": "2026-03-31T23:59:59Z",
      "sent_at": "2026-03-21T15:04:05Z",
      "recipient_email": "buyer@example.com",
      "cc_emails": [
        "owner@example.com"
      ],
      "reference": "PO-1042",
      "snapshot": {
        "merchant_display_name": "Flint Services",
        "customer_display_name": "Avery Buyer",
        "customer_email": "buyer@example.com",
        "line_items": [
          {
            "name": "Consulting session",
            "quantity": 1,
            "unit_price_money": {
              "amount": 15000,
              "currency": "USD"
            },
            "base_subtotal_money": {
              "amount": 15000,
              "currency": "USD"
            },
            "modifier_total_money": {
              "amount": 0,
              "currency": "USD"
            },
            "subtotal_money": {
              "amount": 15000,
              "currency": "USD"
            },
            "discount_money": {
              "amount": 0,
              "currency": "USD"
            },
            "tax_money": {
              "amount": 0,
              "currency": "USD"
            },
            "total_money": {
              "amount": 15000,
              "currency": "USD"
            }
          }
        ],
        "pricing_amounts": {
          "subtotal_money": {
            "amount": 15000,
            "currency": "USD"
          },
          "discount_money": {
            "amount": 0,
            "currency": "USD"
          },
          "charge_money": {
            "amount": 0,
            "currency": "USD"
          },
          "tax_money": {
            "amount": 0,
            "currency": "USD"
          },
          "requested_tip_money": {
            "amount": 0,
            "currency": "USD"
          },
          "total_money": {
            "amount": 15000,
            "currency": "USD"
          }
        },
        "memo": "Payment due within 10 days."
      },
      "outstanding_money": {
        "amount": 15000,
        "currency": "USD"
      },
      "paid_money": {
        "amount": 0,
        "currency": "USD"
      },
      "refunded_money": {
        "amount": 0,
        "currency": "USD"
      },
      "is_overdue": false,
      "created_at": "2026-03-21T15:03:00Z",
      "updated_at": "2026-03-21T15:04:05Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get one of the current buyer's invoices#

GET/v1/me/invoices/{invoice_id}Requires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Returns a single invoice by ID.

Path parameters
invoice_idstringrequired

Flint invoice ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDANGLING_EXPANSION_REFERENCEEXPANSION_DEPENDENCY_UNAVAILABLEEXPANSION_RESOLUTION_FAILEDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_API_KEYINVALID_EXPANDINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/me/invoices/inv_01J00000000000000000000000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Create an invoice checkout session for the current buyer#

POST/v1/me/invoices/{invoice_id}/checkout-sessionIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Returns the current open invoice checkout session and aligned card attempt when they still match the invoice balance and collection run. A newly created session and attempt share the fixed expiration of the active invoice public-link generation. Unexpired sessions are reused regardless of remaining lifetime; active payment work returns a resolving conflict instead of creating competing collection.

Path parameters
invoice_idstringrequired

Flint invoice ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/me/invoices/inv_01J00000000000000000000000/checkout-session \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "invoice": {
      "invoice_id": "inv_01J00000000000000000000000",
      "merchant_id": "mer_01J00000000000000000000000",
      "order_id": "ord_01J00000000000000000000000",
      "customer_id": "cus_01J00000000000000000000000",
      "invoice_number": "1042",
      "status": "open",
      "refund_status": "none",
      "collection_block_status": "",
      "due_at": "2026-03-31T23:59:59Z",
      "sent_at": "2026-03-21T15:04:05Z",
      "recipient_email": "buyer@example.com",
      "cc_emails": [
        "owner@example.com"
      ],
      "reference": "PO-1042",
      "snapshot": {
        "merchant_display_name": "Flint Services",
        "customer_display_name": "Avery Buyer",
        "customer_email": "buyer@example.com",
        "line_items": [
          {
            "name": "Consulting session",
            "quantity": 1,
            "unit_price_money": {
              "amount": 15000,
              "currency": "USD"
            },
            "base_subtotal_money": {
              "amount": 15000,
              "currency": "USD"
            },
            "modifier_total_money": {
              "amount": 0,
              "currency": "USD"
            },
            "subtotal_money": {
              "amount": 15000,
              "currency": "USD"
            },
            "discount_money": {
              "amount": 0,
              "currency": "USD"
            },
            "tax_money": {
              "amount": 0,
              "currency": "USD"
            },
            "total_money": {
              "amount": 15000,
              "currency": "USD"
            }
          }
        ],
        "pricing_amounts": {
          "subtotal_money": {
            "amount": 15000,
            "currency": "USD"
          },
          "discount_money": {
            "amount": 0,
            "currency": "USD"
          },
          "charge_money": {
            "amount": 0,
            "currency": "USD"
          },
          "tax_money": {
            "amount": 0,
            "currency": "USD"
          },
          "requested_tip_money": {
            "amount": 0,
            "currency": "USD"
          },
          "total_money": {
            "amount": 15000,
            "currency": "USD"
          }
        },
        "memo": "Payment due within 10 days."
      },
      "outstanding_money": {
        "amount": 15000,
        "currency": "USD"
      },
      "paid_money": {
        "amount": 0,
        "currency": "USD"
      },
      "refunded_money": {
        "amount": 0,
        "currency": "USD"
      },
      "is_overdue": false,
      "created_at": "2026-03-21T15:03:00Z",
      "updated_at": "2026-03-21T15:04:05Z"
    },
    "invoice_payment_attempt": {
      "invoice_payment_attempt_id": "invpa_01J00000000000000000000000",
      "invoice_id": "inv_01J00000000000000000000000",
      "rail": "card",
      "status": "open",
      "expected_amount_money": {
        "amount": 15000,
        "currency": "USD"
      },
      "checkout_session_id": "cs_01J00000000000000000000000",
      "started_at": "2026-03-21T15:05:00Z"
    },
    "checkout_session": {
      "checkout_session_id": "cs_01J00000000000000000000000",
      "surface": "",
      "delivery_method_ids": null,
      "status": "open",
      "order_id": "ord_01J00000000000000000000000",
      "invoice_id": "inv_01J00000000000000000000000",
      "expires_at": "2026-03-21T16:05:00Z",
      "url": "https://checkout.withflintpay.com/cs/cs_01J00000000000000000000000",
      "recovery_mode": false,
      "delivery_selection_required": false,
      "problems": null
    },
    "hosted_checkout": {
      "url": "https://checkout.withflintpay.com/cs/cs_01J00000000000000000000000",
      "checkout_auth_token": "csauth_example"
    },
    "reused_existing": false
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Download one of the current buyer's invoices#

GET/v1/me/invoices/{invoice_id}/pdfRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Downloads the merchant-authenticated PDF artifact generated from the invoice snapshot.

Path parameters
invoice_idstringrequired

Flint invoice ID.

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/me/invoices/inv_01J00000000000000000000000/pdf \
  -H "Authorization: Bearer YOUR_API_KEY"

List the current buyer's orders#

GET/v1/me/ordersRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Returns a paginated list of orders for the authenticated merchant.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

statusenum

Filter by workflow status.

openclosed
payment_statusenum

Filter by settled collection status.

unpaidpartially_paidpaid
refund_statusenum

Filter by refund progress.

nonepartially_refundedrefunded
fulfillment_statusarray of enum

Filter by aggregate order fulfillment status. Repeat the parameter to OR multiple statuses.

not_fulfilledpartially_fulfilledfulfilledcanceled
order_numberstring

Filter by merchant-visible order number.

external_reference_idstring

Exact-match filter on the caller-owned external reference ID.

originenum

Filter by order origin.

virtual_terminalpayment_linkcheckoutapisubscription
querystring

Search across order number, external_reference_id, fulfillment external_reference_id, notes, and line item names.

subscription_idstring

Filter by subscription ID.

return_idstring

Filter by the Return that created a replacement order.

return_resolution_idstring

Filter by the ReturnResolution that created a replacement order.

min_amountinteger

Inclusive lower bound on the order total in minor units. Requires currency.

max_amountinteger

Inclusive upper bound on the order total in minor units. Requires currency.

currencystring

ISO 4217 currency for min_amount and max_amount.

sort_byenum

Sort field.

created_atupdated_atoutstanding_moneytotal
sort_directionenum

Sort direction.

ascdesc
created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

updated_afterstring

RFC3339 lower bound for updated_at.

updated_beforestring

RFC3339 upper bound for updated_at.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/me/orders \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "order_id": "ord_123",
      "line_items": [
        {
          "order_line_item_id": "li_123",
          "name": "General Admission",
          "quantity": 2,
          "unit_price_money": {
            "amount": 2500,
            "currency": "USD"
          },
          "base_subtotal_money": {
            "amount": 5000,
            "currency": "USD"
          },
          "modifier_total_money": {
            "amount": 0,
            "currency": "USD"
          },
          "subtotal_money": {
            "amount": 5000,
            "currency": "USD"
          },
          "discount_money": {
            "amount": 0,
            "currency": "USD"
          },
          "tax_money": {
            "amount": 0,
            "currency": "USD"
          },
          "refunded_money": {
            "amount": 0,
            "currency": "USD"
          },
          "refunded_quantity": 0,
          "total_money": {
            "amount": 5000,
            "currency": "USD"
          },
          "metadata": {
            "ticket_type": "ga"
          },
          "inventory_snapshot": null
        }
      ],
      "status": "open",
      "payment_status": "unpaid",
      "refund_status": "none",
      "metadata": {
        "event_id": "evt_123"
      },
      "merchant_id": "mer_123",
      "customer_id": "cus_123",
      "pricing_amounts": {
        "subtotal_money": {
          "amount": 5000,
          "currency": "USD"
        },
        "discount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "charge_money": {
          "amount": 0,
          "currency": "USD"
        },
        "tax_money": {
          "amount": 0,
          "currency": "USD"
        },
        "requested_tip_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_money": {
          "amount": 5000,
          "currency": "USD"
        }
      },
      "tax": {
        "enabled": false,
        "status": "",
        "mode": "",
        "taxability_reason": ""
      },
      "settlement_amounts": {
        "paid_money": {
          "amount": 0,
          "currency": "USD"
        },
        "refunded_money": {
          "amount": 0,
          "currency": "USD"
        },
        "net_collected_money": {
          "amount": 0,
          "currency": "USD"
        },
        "settled_tip_money": {
          "amount": 0,
          "currency": "USD"
        },
        "balance_money": {
          "amount": 5000,
          "currency": "USD"
        },
        "outstanding_money": {
          "amount": 5000,
          "currency": "USD"
        },
        "credit_money": {
          "amount": 0,
          "currency": "USD"
        }
      },
      "order_number": "1001",
      "origin": "api",
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z",
      "inventory_demand_revision": 0
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get one of the current buyer's orders#

GET/v1/me/orders/{order_id}Requires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Returns a single order by ID.

Path parameters
order_idstringrequired

Flint order ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDANGLING_EXPANSION_REFERENCEEXPANSION_DEPENDENCY_UNAVAILABLEEXPANSION_RESOLUTION_FAILEDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_API_KEYINVALID_EXPANDINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/me/orders/ord_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

List activity for one of the current buyer's orders#

GET/v1/me/orders/{order_id}/activitiesRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Returns a read-only, human-readable history log for an order. Use it to render timelines and debug what happened, not as a source of truth, ledger, or webhook replacement. Read the owning resource for authoritative state: the order for balances and status, the payment for payment state, the refund for refund outcomes, and the checkout session for checkout state. Do not sum balance_delta_money to compute an order balance. Informational rows such as payment_failed, refund_failed, and checkout_session_expired have a zero balance delta. The default order is newest first. Use sort_direction=asc for chronological timeline rendering. A typical chronological log might show created, payment_failed, payment, refund, then refund_failed; each row gives one reference to click through for the authoritative resource.

Path parameters
order_idstringrequired

Flint order ID.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

sort_directionenum

Sort direction.

ascdesc
typearray of enum

Filter by activity type. Repeat the parameter or pass comma-separated values to OR multiple types.

createdline_item_addedline_item_updatedline_item_removeddiscount_applieddiscount_removedtax_updatedrequested_tip_addedrequested_tip_updatedrequested_tip_removedcharge_addedcharge_updatedcharge_removedcharge_fulfillment_updatedorder_updatedadjustmentclosedpaymentpayment_failedrefundrefund_failedcheckout_session_createdcheckout_session_expiredcheckout_session_invalidatedfulfillment_createdfulfillment_updatedfulfillment_state_changed
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/me/orders/ord_123/activities \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "order_activity_id": "act_123",
      "activity_type": "payment",
      "balance_delta_money": {
        "amount": -5000,
        "currency": "USD"
      },
      "running_balance_money": {
        "amount": 0,
        "currency": "USD"
      },
      "description": "Payment received",
      "payment_intent_id": "pi_123",
      "created_at": "2026-03-17T14:35:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Resend the receipt for one of the current buyer's orders#

POST/v1/me/orders/{order_id}/receiptIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Queues another receipt email for a paid order when Flint manages receipt delivery. The recipient is derived from the order and cannot be supplied by the caller. When the merchant manages receipt delivery, ask the merchant for another copy.

Path parameters
order_idstringrequired

Flint order ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTORDER_RECEIPT_EMAIL_UNAVAILABLEORDER_RECEIPT_MERCHANT_MANAGEDORDER_RECEIPT_NOT_AVAILABLEORDER_RECEIPT_RESEND_RATE_LIMITEDRATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/me/orders/ord_123/receipt \
  -H "Authorization: Bearer YOUR_API_KEY"

List the current buyer's packages#

GET/v1/me/packagesRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Lists package records, newest created first.

Query parameters
shipment_idstring

Optional shipment ID filter.

fulfillment_idstring

Optional fulfillment ID filter.

order_idstring

Optional order ID filter.

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

external_systemstring

Filter by external system identifier.

external_reference_idstring

Filter by caller-owned external package reference.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/me/packages \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "package_id": "pkg_01ABCDEFGHIJKLMNOPQRSTUVWX",
      "order_id": "ord_01ABCDEFGHIJKLMNOPQRSTUVWX",
      "fulfillment_id": "ful_01ABCDEFGHIJKLMNOPQRSTUVWX",
      "shipment_id": "shp_01ABCDEFGHIJKLMNOPQRSTUVWX",
      "status": "created",
      "carrier": "ups",
      "service_code": "ground",
      "tracking_number": "1Z999AA10123456784",
      "tracking_url": "https://track.example.com/1Z999AA10123456784",
      "weight": {
        "value": 1.2,
        "unit": "lb"
      },
      "dimensions": {
        "length": 8,
        "width": 6,
        "height": 4,
        "unit": "in"
      },
      "external_system": "merchant_wms",
      "external_reference_id": "pkg_789",
      "metadata": {
        "box": "small"
      },
      "created_at": "2026-05-13T16:01:00Z",
      "updated_at": "2026-05-13T16:01:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List the current buyer's payment methods#

GET/v1/me/payment-methodsRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Returns saved payment methods for the merchant, optionally filtered to a customer. By default, only active payment methods are returned.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

typeenum

Filter by payment method type.

card
statusenum

Filter by payment method status.

activependingexpiredremovedfailed
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/me/payment-methods \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "payment_method_id": "pm_123",
      "customer_id": "cus_123",
      "type": "card",
      "status": "active",
      "merchant_id": "mer_123",
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z",
      "card": {
        "last4": "4242",
        "brand": "visa",
        "exp_month": 12,
        "exp_year": 2030
      }
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Add a payment method for the current buyer#

POST/v1/me/payment-methodsIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Initiates saving a payment method and returns the client setup payload needed to complete setup on the frontend.

Request body
payment_method_typeenum
card
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/me/payment-methods \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "payment_method_type": "card"
  }'
JSON
{
  "data": {
    "payment_method": {
      "payment_method_id": "pm_123",
      "customer_id": "cus_123",
      "type": "card",
      "status": "pending",
      "merchant_id": "mer_123",
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z"
    },
    "client_setup": {
      "stripe": {
        "account_id": "acct_123",
        "publishable_key": "pk_test_123",
        "setup_intent": {
          "stripe_js_call": "confirm_setup",
          "client_secret": "seti_secret_123"
        }
      }
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Remove one of the current buyer's payment methods#

DELETE/v1/me/payment-methods/{payment_method_id}IdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Soft-removes a saved payment method so it can no longer be used for future payments.

Path parameters
payment_method_idstringrequired

Flint payment method ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X DELETE https://api.withflintpay.com/v1/me/payment-methods/pm_123 \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "success": true
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Set the current buyer's default payment method#

POST/v1/me/payment-methods/{payment_method_id}/set-defaultIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Sets the default payment method for the payment method's owning customer.

Path parameters
payment_method_idstringrequired

Flint payment method ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/me/payment-methods/pm_123/set-default \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "payment_method_id": "pm_123",
    "customer_id": "cus_123",
    "type": "card",
    "status": "active",
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "card": {
      "last4": "4242",
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2030
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List the current buyer's payments#

GET/v1/me/paymentsRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Returns a paginated list of payment intents for the authenticated merchant.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

order_idstring

Filter by order ID.

invoice_idstring

Filter by invoice ID.

statusenum

Filter by payment intent status.

requires_payment_methodrequires_confirmationrequires_actionprocessingrequires_capturecanceledsucceededexpired
originenum

Filter by payment origin.

virtual_terminalpayment_linkcheckoutapisubscription
risk_levelarray of enum

Filter by the latest completed risk assessment. Repeat or comma-separate values.

normalelevatedhighestnot_assessed
payment_flowarray of enum

Filter by immutable payment flow. Repeat or comma-separate values.

checkoutpayment_linkinvoicesubscription_initialsubscription_renewalvirtual_terminalapi
external_reference_idstring

Exact-match filter on the merchant reference ID.

return_idstring

Filter by linked Return ID.

return_resolution_idstring

Filter by linked ReturnResolution ID.

querystring

Search across payment_intent_id, external_reference_id, and receipt_email.

min_amountinteger

Inclusive lower bound in minor units. Requires currency.

max_amountinteger

Inclusive upper bound in minor units. Requires currency.

currencystring

ISO 4217 currency for min_amount and max_amount.

stateenum

Filter by aggregate payment-intent state preset.

with_refundsfully_refundeddisputedneeds_action
sort_byenum

Sort field.

created_atupdated_atamount
sort_directionenum

Sort direction.

ascdesc
created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

updated_afterstring

RFC3339 lower bound for updated_at.

updated_beforestring

RFC3339 upper bound for updated_at.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/me/payments \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "amount_money": {
        "amount": 5000,
        "currency": "USD"
      },
      "capture_method": "automatic",
      "created_at": "2026-03-17T14:30:00Z",
      "customer_id": "cus_123",
      "external_reference_id": "cart_123",
      "last_payment_error": null,
      "merchant_id": "mer_123",
      "metadata": {
        "channel": "web"
      },
      "origin": "api",
      "payment_flow": "",
      "payment_intent_id": "pi_123",
      "payment_options": [
        "card",
        "apple_pay"
      ],
      "receipt_email": "buyer@example.com",
      "refund_status": "none",
      "risk": null,
      "settlement_status": "none",
      "status": "requires_confirmation",
      "support_reference": "",
      "updated_at": "2026-03-17T14:30:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List the current buyer's refunds#

GET/v1/me/refundsRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Returns a paginated list of refunds for the authenticated merchant.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

order_idstring

Filter by order ID.

payment_intent_idstring

Filter by payment intent ID.

statusenum

Filter by refund status.

pendingin_transitsucceededfailedrequires_actioncanceledpartially_succeeded
reasonarray of enum

Repeat the parameter to filter by multiple refund reasons.

duplicatefraudulentrequested_by_customerdefective_productwrong_item_shippednever_receivednot_as_describedarrived_too_latecustomer_changed_mindbetter_price_foundaccidental_orderother
refund_methodenum

Filter by refund method.

original_payment
min_amountinteger

Inclusive lower bound in minor units. Requires currency.

max_amountinteger

Inclusive upper bound in minor units. Requires currency.

currencystring

ISO 4217 currency for min_amount and max_amount.

external_reference_idstring

Exact-match filter on the caller-owned external reference ID.

return_idstring

Filter by linked Return ID.

return_resolution_idstring

Filter by linked ReturnResolution ID.

querystring

Search across refund_id, external_reference_id, and reason_message.

sort_byenum

Sort field.

created_atupdated_atamount
sort_directionenum

Sort direction.

ascdesc
created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

updated_afterstring

RFC3339 lower bound for updated_at.

updated_beforestring

RFC3339 upper bound for updated_at.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/me/refunds \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "refund_id": "ref_123",
      "amount_money": {
        "amount": 1000,
        "currency": "USD"
      },
      "refunded_tip_money": {
        "amount": 100,
        "currency": "USD"
      },
      "status": "succeeded",
      "reason": "requested_by_customer",
      "metadata": {
        "ticket_id": "tkt_123"
      },
      "merchant_id": "mer_123",
      "order_id": "ord_123",
      "payment_intent_id": "pi_123",
      "refund_method": "original_payment",
      "customer_id": "cus_123",
      "payment_refunds": [
        {
          "payment_intent_id": "pi_123",
          "amount_money": {
            "amount": 1000,
            "currency": "USD"
          },
          "refunded_tip_money": {
            "amount": 100,
            "currency": "USD"
          },
          "status": "succeeded"
        }
      ],
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Check Return eligibility for the current buyer#

POST/v1/me/return-eligibility-checksIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Evaluate every remaining fulfilled allocation or an explicit selection without creating a Return or reserving quantity. The result is advisory and may become stale immediately.

Request body
order_idstringrequired
selectionone ofrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/me/return-eligibility-checks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "order_id": "",
    "selection": {
      "selection_type": "all_remaining_fulfilled"
    }
  }'

Preview a Return resolution for the current buyer#

POST/v1/me/return-resolution-previewsIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Calculate resolution amounts and warnings without reserving value or creating a resolution. Requested Returns use eligible policy capacity; open Returns use committed approved capacity. The result is advisory and tied to based_on_return_revision.

Request body
option 1object
option 2object
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/me/return-resolution-previews \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "resolution_type": "refund",
    "return_id": ""
  }'

Create a Return resolution checkout session for the current buyer#

POST/v1/me/return-resolutions/{resolution_id}/checkout-sessionIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Create or reuse the standard hosted checkout session for a buyer-owed replacement Order linked to this Return resolution.

Path parameters
resolution_idstringrequired

Flint return resolution id.

Response · 201
dataobjectrequired

Checkout-session access returned for hosted or embedded checkout creation.

metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/me/return-resolutions/{resolution_id}/checkout-session \
  -H "Authorization: Bearer YOUR_API_KEY"

List the current buyer's Returns#

GET/v1/me/returnsRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. List Returns for the merchant, filtered by order, customer, status, decision, merchandise, resolution, or creation window. Filter by idempotency_key to recover a create whose response never arrived.

Query parameters
created_afterstring

RFC3339 created after filter.

created_beforestring

RFC3339 created before filter.

decision_statusarray of enum

Filter by decision status.

pendingapprovedpartially_approveddeclined
external_reference_idstring

Filter by external reference id.

idempotency_keystring

Filter by idempotency key.

merchandise_statusarray of enum

Filter by merchandise status.

not_requiredawaiting_handoffin_transitpartially_receivedreceivedinspection_requiredpartially_inspectedinspection_review_requireddisposition_requiredresolvedexception
order_idstring

Filter by order id.

page_sizeinteger

Page size. Defaults to 20 and is capped at 100.

page_tokenstring

Opaque cursor returned by the previous page.

receiving_location_idstring

Filter by receiving location id.

resolution_statusarray of enum

Filter by resolution status.

not_selectedpendingpartially_fulfilledrequires_actionfulfilledfailed
resolution_typearray of enum

Filter by resolution type.

refundexchangereplacementno_monetary_actioncorrection
return_numberstring

Filter by return number.

return_reason_idstring

Filter by return reason id.

statusarray of enum

Filter by status.

requestedopencompleteddeclinedcanceled
updated_afterstring

RFC3339 updated after filter.

updated_beforestring

RFC3339 updated before filter.

work_typearray of enum

Filter by work type.

decisionhandoffreceiptinspectiondispositionresolutionexception
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/me/returns \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a Return for the current buyer#

POST/v1/me/returnsIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Create a requested Return. When no policy matches, the Return remains available for merchant review rather than failing creation.

Request body
external_reference_idstring
line_itemsarray of objectrequired
metadatamap of string
order_idstringrequired
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/me/returns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "line_items": [
      {
        "order_line_item_id": "",
        "requested_quantity": 0,
        "return_reason_id": ""
      }
    ],
    "order_id": ""
  }'

Get one of the current buyer's Returns#

GET/v1/me/returns/{return_id}Requires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Retrieve a Return with its line items, policy evaluation, financial summary, and completion blockers. Supports expand for the order, the customer, and each line item's reason and fulfillment.

Path parameters
return_idstringrequired

Flint return id.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDANGLING_EXPANSION_REFERENCEEXPANSION_DEPENDENCY_UNAVAILABLEEXPANSION_RESOLUTION_FAILEDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/me/returns/ret_01K0P7W6A4N9F3J2T8Q5R1C6XM \
  -H "Authorization: Bearer YOUR_API_KEY"

Cancel one of the current buyer's Returns#

POST/v1/me/returns/{return_id}/cancelIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Cancel a Return before any merchandise or value work commits. Cancellation is refused once a receipt, inspection, disposition, or resolution exists.

Path parameters
return_idstringrequired

Flint return id.

Request body
expected_return_revisionintegerrequired
reasonenumrequired
buyer_requestmerchant_requestduplicateexpiredcreated_in_errorother
reason_messagestring
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/me/returns/ret_01K0P7W6A4N9F3J2T8Q5R1C6XM/cancel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_return_revision": 0,
    "reason": "buyer_request"
  }'

List the current buyer's shipments#

GET/v1/me/shipmentsRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Lists shipment execution records, newest created first.

Query parameters
order_idstring

Optional order ID filter.

fulfillment_idstring

Optional fulfillment ID filter.

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

external_systemstring

Filter by external system identifier.

external_reference_idstring

Filter by caller-owned external shipment reference.

return_idstring

Filter by linked Return ID.

handed_off_afterstring

RFC3339 lower bound for handed_off_at.

handed_off_beforestring

RFC3339 upper bound for handed_off_at.

created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/me/shipments \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "shipment_id": "shp_01ABCDEFGHIJKLMNOPQRSTUVWX",
      "order_id": "ord_01ABCDEFGHIJKLMNOPQRSTUVWX",
      "fulfillment_id": "ful_01ABCDEFGHIJKLMNOPQRSTUVWX",
      "direction": "outbound",
      "status": "created",
      "package_count": 0,
      "shipped_at": "2026-05-13T16:00:00Z",
      "handed_off_at": "2026-05-13T16:00:00Z",
      "external_system": "merchant_wms",
      "external_reference_id": "ship_789",
      "metadata": {
        "warehouse": "east"
      },
      "created_at": "2026-05-13T15:59:00Z",
      "updated_at": "2026-05-13T16:00:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List the current buyer's subscriptions#

GET/v1/me/subscriptionsRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Returns a paginated list of subscriptions for the authenticated merchant.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

statusenum

Filter by subscription status.

trialingactivepausedpast_duecanceledincomplete
plan_idstring

Filter by Flint subscription plan ID.

querystring

Search across customer name/email and plan name.

sort_byenum

Sort field.

created_atupdated_atnext_billing_at
sort_directionenum

Sort direction.

ascdesc
created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

updated_afterstring

RFC3339 lower bound for updated_at.

updated_beforestring

RFC3339 upper bound for updated_at.

next_billing_at_afterstring

RFC3339 lower bound for next_billing_at.

next_billing_at_beforestring

RFC3339 upper bound for next_billing_at.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/me/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "subscription_id": "sub_123",
      "plan_id": "plan_123",
      "customer_id": "cus_123",
      "payment_method_id": "pm_123",
      "status": "active",
      "billing_anchor_day": 15,
      "cancel_at_period_end": false,
      "current_period_start": "2026-03-17T14:30:00Z",
      "current_period_end": "2026-04-17T14:30:00Z",
      "next_billing_at": "2026-04-17T14:30:00Z",
      "metadata": {
        "source": "api"
      },
      "merchant_id": "mer_123",
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get one of the current buyer's subscriptions#

GET/v1/me/subscriptions/{subscription_id}Requires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Returns a single subscription by ID.

Path parameters
subscription_idstringrequired

Flint subscription ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDANGLING_EXPANSION_REFERENCEEXPANSION_DEPENDENCY_UNAVAILABLEEXPANSION_RESOLUTION_FAILEDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/me/subscriptions/sub_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Cancel one of the current buyer's subscriptions#

POST/v1/me/subscriptions/{subscription_id}/cancelIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Cancels a subscription immediately or at period end. Response may include advisory contract information.

Path parameters
subscription_idstringrequired

Flint subscription ID.

Request body
cancel_immediatelyboolean
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/me/subscriptions/sub_123/cancel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "cancel_immediately": false
  }'
JSON
{
  "data": {
    "subscription_id": "sub_123",
    "plan_id": "plan_123",
    "customer_id": "cus_123",
    "payment_method_id": "pm_123",
    "status": "active",
    "billing_anchor_day": 15,
    "cancel_at_period_end": true,
    "current_period_start": "2026-03-17T14:30:00Z",
    "current_period_end": "2026-04-17T14:30:00Z",
    "next_billing_at": "2026-04-17T14:30:00Z",
    "metadata": {
      "source": "api"
    },
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-20T10:00:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Pause one of the current buyer's subscriptions#

POST/v1/me/subscriptions/{subscription_id}/pauseIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Pauses a subscription immediately, optionally for a fixed number of billing cycles.

Path parameters
subscription_idstringrequired

Flint subscription ID.

Request body
pause_duration_cyclesinteger
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/me/subscriptions/sub_123/pause \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "pause_duration_cycles": 2
  }'
JSON
{
  "data": {
    "subscription_id": "sub_123",
    "plan_id": "plan_123",
    "customer_id": "cus_123",
    "payment_method_id": "pm_123",
    "status": "active",
    "billing_anchor_day": 15,
    "cancel_at_period_end": false,
    "current_period_start": "2026-03-17T14:30:00Z",
    "current_period_end": "2026-04-17T14:30:00Z",
    "next_billing_at": "2026-04-17T14:30:00Z",
    "metadata": {
      "source": "api"
    },
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Change the payment method for one of the current buyer's subscriptions#

POST/v1/me/subscriptions/{subscription_id}/payment-methodIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Changes the subscription to an active payment method owned by the same customer.

Path parameters
subscription_idstringrequired

Flint subscription ID.

Request body
payment_method_idstringrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/me/subscriptions/sub_123/payment-method \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "payment_method_id": "pm_123"
  }'

Reactivate one of the current buyer's subscriptions#

POST/v1/me/subscriptions/{subscription_id}/reactivateIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Clears a pending period-end cancellation without changing the current billing period.

Path parameters
subscription_idstringrequired

Flint subscription ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/me/subscriptions/sub_123/reactivate \
  -H "Authorization: Bearer YOUR_API_KEY"

Resume one of the current buyer's subscriptions#

POST/v1/me/subscriptions/{subscription_id}/resumeIdempotentRequires CustomerSessionBearer

Uses the customer identity fixed by the customer session. The request cannot select a customer_id. Resumes a paused subscription.

Path parameters
subscription_idstringrequired

Flint subscription ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/me/subscriptions/sub_123/resume \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "subscription_id": "sub_123",
    "plan_id": "plan_123",
    "customer_id": "cus_123",
    "payment_method_id": "pm_123",
    "status": "active",
    "billing_anchor_day": 15,
    "cancel_at_period_end": false,
    "current_period_start": "2026-03-17T14:30:00Z",
    "current_period_end": "2026-04-17T14:30:00Z",
    "next_billing_at": "2026-04-17T14:30:00Z",
    "metadata": {
      "source": "api"
    },
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc