{ "openapi": "3.1.0", "info": { "title": "Flex API", "description": "The Flex API powers HSA/FSA payment processing for healthcare commerce: checkout sessions, payment intents, subscriptions, customers, refunds, disputes, and eligibility. Authenticate with your partner API key as a Bearer token. All endpoints are scoped to your partner account, and test mode is fully supported via test API keys.", "version": "0.1.0" }, "servers": [ { "url": "https://api.withflex.com" } ], "paths": { "/v1/shipping_rates": { "get": { "tags": [ "Shipping Rates" ], "summary": "List Shipping Rates", "description": "Returns a list of your shipping rates, most recent first. Pass `active` to return only active\nor only archived rates.", "operationId": "v1.shipping_rates.list", "parameters": [ { "in": "query", "name": "active", "description": "Only return shipping rates where `active` matches this value.", "schema": { "description": "Only return shipping rates where `active` matches this value.", "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int64", "maximum": 9007199254740991.0, "minimum": -9007199254740991.0 }, "style": "form", "example": 10 }, { "in": "query", "name": "offset", "description": "Number of objects to skip before returning results.", "schema": { "description": "Number of objects to skip before returning results.", "examples": [ 3 ], "type": [ "integer", "null" ], "format": "int64", "maximum": 9007199254740991.0, "minimum": -9007199254740991.0 }, "style": "form", "example": 3 }, { "in": "query", "name": "starting_after", "description": "A cursor for use in pagination. `starting_after` is a shipping rate ID that defines your place in the list.", "schema": { "description": "A cursor for use in pagination. `starting_after` is a shipping rate ID that defines your place in the list.", "examples": [ "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "A cursor for use in pagination. `ending_before` is a shipping rate ID that defines your place in the list.", "schema": { "description": "A cursor for use in pagination. `ending_before` is a shipping rate ID that defines your place in the list.", "examples": [ "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a list of shipping rate objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleShippingRatesBody_for_V1ShippingRate" }, "example": { "shipping_rates": [ { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "active": false, "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } }, "post": { "tags": [ "Shipping Rates" ], "summary": "Create Shipping Rate", "description": "Creates a new shipping rate. The rate is a fixed amount denominated in USD. New shipping rates\nare `active` by default.", "operationId": "v1.shipping_rates.create", "requestBody": { "description": "An envelope wrapping a single shipping rate object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRateBody_for_CreateShippingRateRequest" }, "example": { "shipping_rate": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single shipping rate object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRateBody_for_V1ShippingRate" }, "example": { "shipping_rate": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "active": false, "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/shipping_rates/{id}": { "get": { "tags": [ "Shipping Rates" ], "summary": "Get Shipping Rate", "description": "Retrieves the shipping rate with the given ID.", "operationId": "v1.shipping_rates.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single shipping rate object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRateBody_for_V1ShippingRate" }, "example": { "shipping_rate": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "active": false, "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } }, "put": { "tags": [ "Shipping Rates" ], "summary": "Update Shipping Rate", "description": "Updates the specified shipping rate. You can update `active` and `metadata`; both are\noverwritten with the values passed, and omitting `metadata` clears it. The shipping rate's\n`display_name` and `amount` are immutable.", "operationId": "v1.shipping_rates.update", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single shipping rate object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRateBody_for_UpdateShippingRateRequest" }, "example": { "shipping_rate": { "metadata": { "order_id": "8842", "channel": "shopify" }, "active": false } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single shipping rate object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRateBody_for_V1ShippingRate" }, "example": { "shipping_rate": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "active": false, "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/disputes": { "get": { "tags": [ "Disputes" ], "summary": "List Disputes", "description": "Returns a list of your disputes, most recent first.\n\nEvidence is omitted by default; pass `expand=evidence` to include the parsed evidence for each dispute.", "operationId": "v1.disputes.list", "parameters": [ { "in": "query", "name": "limit", "description": "Maximum number of disputes to return (default 20, max 100).", "schema": { "description": "Maximum number of disputes to return (default 20, max 100).", "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int64", "maximum": 9007199254740991.0, "minimum": -9007199254740991.0 }, "style": "form", "example": 10 }, { "in": "query", "name": "starting_after", "description": "A cursor for use in pagination. `starting_after` is a dispute ID that defines your place in the list. For instance, if you make a list request and receive 20 disputes, ending with `fdp_xyz`, your subsequent call can include `starting_after=fdp_xyz` to fetch the next page of the list.", "schema": { "description": "A cursor for use in pagination. `starting_after` is a dispute ID that defines your place in the list. For instance, if you make a list request and receive 20 disputes, ending with `fdp_xyz`, your subsequent call can include `starting_after=fdp_xyz` to fetch the next page of the list.", "examples": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "A cursor for use in pagination. `ending_before` is a dispute ID that defines your place in the list. For instance, if you make a list request and receive 20 disputes, starting with `fdp_abc`, your subsequent call can include `ending_before=fdp_abc` to fetch the previous page of the list.", "schema": { "description": "A cursor for use in pagination. `ending_before` is a dispute ID that defines your place in the list. For instance, if you make a list request and receive 20 disputes, starting with `fdp_abc`, your subsequent call can include `ending_before=fdp_abc` to fetch the previous page of the list.", "examples": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "charge", "description": "Filter by charge ID.", "schema": { "description": "Filter by charge ID.", "examples": [ "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "payment_intent", "description": "Filter by payment intent ID.", "schema": { "description": "Filter by payment intent ID.", "examples": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "statuses", "description": "Filter by dispute statuses (comma-separated, e.g. `?statuses=needs_response,under_review`).", "schema": { "description": "Filter by dispute statuses (comma-separated, e.g. `?statuses=needs_response,under_review`).", "default": null, "examples": [ "needs_response" ], "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DisputeStatus" } }, "style": "form", "example": "needs_response" }, { "in": "query", "name": "expand", "description": "Comma-separated list of fields to expand (e.g., `?expand=evidence`).", "schema": { "description": "Comma-separated list of fields to expand (e.g., `?expand=evidence`).", "default": "", "type": "string" }, "style": "form" } ], "responses": { "200": { "description": "An envelope wrapping a list of dispute objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleDisputesBody_for_Dispute" }, "example": { "disputes": [ { "dispute_id": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "currency": "usd", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "status": "lost", "reason": "bank_cannot_process", "is_charge_refundable": false, "evidence": { "access_activity_log": "string", "customer_name": "string", "customer_email_address": "string", "customer_purchase_ip": "string", "billing_address": "string", "shipping_address": "string", "shipping_tracking_number": "string", "shipping_carrier": "string", "shipping_date": "string", "service_date": "string", "product_description": "string", "refund_policy_disclosure": "string", "refund_refusal_explanation": "string", "cancellation_policy_disclosure": "string", "cancellation_rebuttal": "string", "duplicate_charge_explanation": "string", "duplicate_charge_id": "string", "uncategorized_text": "string", "customer_communication": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "customer_signature": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "shipping_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "receipt": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "duplicate_charge_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "service_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "uncategorized_file": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "cancellation_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "refund_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" } }, "evidence_details": { "due_by": "2026-06-15T14:30:00Z", "has_evidence": false, "past_due": false, "submission_count": 3 }, "balance_transactions": [ { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "fee": 2500, "net": 2500, "status": "available", "type": "string", "reporting_category": "example_value", "category": "example_value", "created_at": "2026-06-15T14:30:00Z" } ], "payment_method_details": { "type": "string", "card": { "brand": "visa", "network_reason_code": "example_value" } }, "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "disputes:read" ] } ], "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } } }, "/v1/disputes/count": { "get": { "tags": [ "Disputes" ], "summary": "Count Disputes", "description": "Returns the number of disputes that currently require a response.\n\nCounts disputes in a `needs_response` or `warning_needs_response` status. Useful for surfacing a \"disputes needing action\" badge without paging through the full list.", "operationId": "v1.disputes.count", "responses": { "200": { "description": "The number of disputes that currently require a response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeCountBody" }, "example": { "count": 3 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "disputes:read" ] } ] } }, "/v1/disputes/{dispute_id}": { "get": { "tags": [ "Disputes" ], "summary": "Get Dispute", "description": "Retrieves the details of an existing dispute.\n\nRetrieves a dispute by ID, including its evidence, evidence submission details, payment method details, and associated balance transactions.", "operationId": "v1.disputes.get", "parameters": [ { "in": "path", "name": "dispute_id", "required": true, "schema": { "examples": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single dispute object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeBody_for_Dispute" }, "example": { "dispute": { "dispute_id": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "currency": "usd", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "status": "lost", "reason": "bank_cannot_process", "is_charge_refundable": false, "evidence": { "access_activity_log": "string", "customer_name": "string", "customer_email_address": "string", "customer_purchase_ip": "string", "billing_address": "string", "shipping_address": "string", "shipping_tracking_number": "string", "shipping_carrier": "string", "shipping_date": "string", "service_date": "string", "product_description": "string", "refund_policy_disclosure": "string", "refund_refusal_explanation": "string", "cancellation_policy_disclosure": "string", "cancellation_rebuttal": "string", "duplicate_charge_explanation": "string", "duplicate_charge_id": "string", "uncategorized_text": "string", "customer_communication": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "customer_signature": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "shipping_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "receipt": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "duplicate_charge_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "service_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "uncategorized_file": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "cancellation_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "refund_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" } }, "evidence_details": { "due_by": "2026-06-15T14:30:00Z", "has_evidence": false, "past_due": false, "submission_count": 3 }, "balance_transactions": [ { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "fee": 2500, "net": 2500, "status": "available", "type": "string", "reporting_category": "example_value", "category": "example_value", "created_at": "2026-06-15T14:30:00Z" } ], "payment_method_details": { "type": "string", "card": { "brand": "visa", "network_reason_code": "example_value" } }, "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "disputes:read" ] } ] }, "post": { "tags": [ "Disputes" ], "summary": "Update Dispute", "description": "Updates the evidence on a dispute, and optionally submits it to the card network.\n\nSaves the provided evidence fields, leaving any omitted fields unchanged; a file field sent as `\"\"` is cleared. File fields reference Flex file IDs that must have purpose `dispute_evidence`; they are resolved to the underlying card-network files before submission. When `submit` is `true`, the evidence is finalized and submitted to the network to contest the dispute — evidence cannot be edited after submission.\n\nThe dispute must be in a `needs_response` or `warning_needs_response` status.", "operationId": "v1.disputes.update", "parameters": [ { "in": "path", "name": "dispute_id", "required": true, "schema": { "examples": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single dispute object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeBody_for_UpdateDispute" }, "example": { "dispute": { "evidence": { "access_activity_log": "example_value", "billing_address": "123 Main St", "cancellation_policy": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "cancellation_policy_disclosure": "example_value", "cancellation_rebuttal": "example_value", "customer_communication": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer_email_address": "john.doe@example.com", "customer_name": "Example", "customer_purchase_ip": "example_value", "customer_signature": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "duplicate_charge_documentation": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "duplicate_charge_explanation": "example_value", "duplicate_charge_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_description": "Premium SPF 50 mineral sunscreen", "receipt": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "refund_policy": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "refund_policy_disclosure": "example_value", "refund_refusal_explanation": "example_value", "service_date": "example_value", "service_documentation": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_address": "123 Main St", "shipping_carrier": "example_value", "shipping_date": "example_value", "shipping_documentation": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_tracking_number": "example_value", "uncategorized_file": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "uncategorized_text": "example_value" }, "submit": false } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single dispute object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeBody_for_Dispute" }, "example": { "dispute": { "dispute_id": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "currency": "usd", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "status": "lost", "reason": "bank_cannot_process", "is_charge_refundable": false, "evidence": { "access_activity_log": "string", "customer_name": "string", "customer_email_address": "string", "customer_purchase_ip": "string", "billing_address": "string", "shipping_address": "string", "shipping_tracking_number": "string", "shipping_carrier": "string", "shipping_date": "string", "service_date": "string", "product_description": "string", "refund_policy_disclosure": "string", "refund_refusal_explanation": "string", "cancellation_policy_disclosure": "string", "cancellation_rebuttal": "string", "duplicate_charge_explanation": "string", "duplicate_charge_id": "string", "uncategorized_text": "string", "customer_communication": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "customer_signature": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "shipping_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "receipt": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "duplicate_charge_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "service_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "uncategorized_file": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "cancellation_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "refund_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" } }, "evidence_details": { "due_by": "2026-06-15T14:30:00Z", "has_evidence": false, "past_due": false, "submission_count": 3 }, "balance_transactions": [ { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "fee": 2500, "net": 2500, "status": "available", "type": "string", "reporting_category": "example_value", "category": "example_value", "created_at": "2026-06-15T14:30:00Z" } ], "payment_method_details": { "type": "string", "card": { "brand": "visa", "network_reason_code": "example_value" } }, "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "disputes:write" ] } ] } }, "/v1/disputes/{dispute_id}/close": { "post": { "tags": [ "Disputes" ], "summary": "Close Dispute", "description": "Closes a dispute, accepting it as lost and forfeiting the disputed funds.\n\nUse this when you do not wish to contest the dispute. Closing is irreversible: it forfeits the disputed amount and the dispute fee, and no further evidence can be submitted. The dispute must be in a `needs_response` or `warning_needs_response` status.", "operationId": "v1.disputes.close", "parameters": [ { "in": "path", "name": "dispute_id", "required": true, "schema": { "examples": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single dispute object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeBody_for_Dispute" }, "example": { "dispute": { "dispute_id": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "currency": "usd", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "status": "lost", "reason": "bank_cannot_process", "is_charge_refundable": false, "evidence": { "access_activity_log": "string", "customer_name": "string", "customer_email_address": "string", "customer_purchase_ip": "string", "billing_address": "string", "shipping_address": "string", "shipping_tracking_number": "string", "shipping_carrier": "string", "shipping_date": "string", "service_date": "string", "product_description": "string", "refund_policy_disclosure": "string", "refund_refusal_explanation": "string", "cancellation_policy_disclosure": "string", "cancellation_rebuttal": "string", "duplicate_charge_explanation": "string", "duplicate_charge_id": "string", "uncategorized_text": "string", "customer_communication": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "customer_signature": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "shipping_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "receipt": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "duplicate_charge_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "service_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "uncategorized_file": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "cancellation_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "refund_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" } }, "evidence_details": { "due_by": "2026-06-15T14:30:00Z", "has_evidence": false, "past_due": false, "submission_count": 3 }, "balance_transactions": [ { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "fee": 2500, "net": 2500, "status": "available", "type": "string", "reporting_category": "example_value", "category": "example_value", "created_at": "2026-06-15T14:30:00Z" } ], "payment_method_details": { "type": "string", "card": { "brand": "visa", "network_reason_code": "example_value" } }, "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "disputes:write" ] } ] } }, "/v1/events/{id}/retry": { "post": { "tags": [ "Events" ], "summary": "Retry Event", "description": "Redeliver an existing event to your webhook endpoints. The event is looked\nup by ID; a `404` is returned if no matching event exists.\n\nIf a `webhook_id` is supplied in the body, the original event is redelivered\nto that specific webhook endpoint and the stored event is\nreturned. If no body is supplied, the event is redelivered to all of your\nconfigured webhook endpoints; in this mode only `checkout.session.completed`\nevents are supported — the checkout session is re-fetched with its related\nobjects expanded and a new event (with a fresh `fevt_` id) is generated and\ndelivered.", "operationId": "v1.events.retry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fevt_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fevt_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single event object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventBody_for_RetryEventRequest" }, "example": { "event": { "webhook_id": "fwh_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single event object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventBody_for_Event" }, "example": { "event": { "event_id": "fevt_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "event_type": "account.updated", "object": { "external_partner": { "origin": "shopify", "domain": "example_value", "flex_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "access_token": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z" }, "customer": { "customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D", "owner_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false }, "checkout_session": { "allow_promotion_codes": false, "amount_total": 2500, "amount_subtotal": 2500, "amount_received": 2500, "amount_refunded": 2500, "amount_disputed": 2500, "cancel_url": "https://example.com", "captures": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "disputes": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "capture_method": "automatic", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "example_value", "created_at": 2500, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "expires_at": 2500, "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "hsa_fsa_eligible": false, "letter_of_medical_necessity_required": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "mode": "payment", "origin": "shopify", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intents": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "redirect_url": "https://example.com", "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "shipping_address_collection": false, "shipping_details": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "open", "success_url": "https://example.com", "fees": [ { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } }, "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription_data": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "test_mode": false, "total_details": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "visit_type": "cbtSleep", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "next_action": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "selling_plans": [ { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } ], "shopify_payment_details": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } }, "renewal_as_of": 1781533800, "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "platform_fees": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } }, "subscription": { "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "quantity": 2500, "created_at": "2026-06-15T14:30:00Z", "updated_at": "2026-06-15T14:30:00Z", "test_mode": false } ], "latest_invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "incomplete", "cancel_at_period_end": false, "current_period_end": "string", "current_period_start": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false, "client_secret": { "setup_secret": "string", "payment_secret": "string" }, "proration_behavior": "always_invoice", "trial_start": "string", "trial_end": "string", "cancel_at": "2026-06-15T14:30:00Z", "canceled_at": "2026-06-15T14:30:00Z", "default_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "discounts": [ { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } ], "pause": { "paused_at": "2026-06-15T14:30:00Z", "resume_at": "2026-06-15T14:30:00Z" } }, "payment_intent": { "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "amount_capturable": 2500, "amount_received": 2500, "application_fee_amount": 0, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "transfer_data": { "amount": 2500, "destination": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "status": "canceled", "latest_charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "capture_method": "automatic", "client_secret": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "transfer_group": "example_value", "payment_card_type": "primary", "letter_fee_amount": 0, "transaction_fee": 0, "last_payment_error": { "type": "string", "code": "string", "decline_code": "string", "message": "string", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "setup_intent": { "setup_intent_id": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_secret": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "status": "requires_payment_method", "usage": "off_session", "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "invoice": { "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "total": 2500, "amount_due": 2500, "amount_paid": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "period_end": "string", "period_start": "string", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "paid_at": "string", "status": "draft", "collection_method": "charge_automatically", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "backup_charge_status": "pending" }, "dispute": { "dispute_id": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "currency": "usd", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "status": "lost", "reason": "bank_cannot_process", "is_charge_refundable": false, "evidence": { "access_activity_log": "string", "customer_name": "string", "customer_email_address": "string", "customer_purchase_ip": "string", "billing_address": "string", "shipping_address": "string", "shipping_tracking_number": "string", "shipping_carrier": "string", "shipping_date": "string", "service_date": "string", "product_description": "string", "refund_policy_disclosure": "string", "refund_refusal_explanation": "string", "cancellation_policy_disclosure": "string", "cancellation_rebuttal": "string", "duplicate_charge_explanation": "string", "duplicate_charge_id": "string", "uncategorized_text": "string", "customer_communication": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "customer_signature": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "shipping_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "receipt": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "duplicate_charge_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "service_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "uncategorized_file": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "cancellation_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "refund_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" } }, "evidence_details": { "due_by": "2026-06-15T14:30:00Z", "has_evidence": false, "past_due": false, "submission_count": 3 }, "balance_transactions": [ { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "fee": 2500, "net": 2500, "status": "available", "type": "string", "reporting_category": "example_value", "category": "example_value", "created_at": "2026-06-15T14:30:00Z" } ], "payment_method_details": { "type": "string", "card": { "brand": "visa", "network_reason_code": "example_value" } }, "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "early_fraud_warning": { "early_fraud_warning_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "actionable": false, "fraud_type": "card_never_received", "partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z" }, "review": { "review_id": "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reason": "rule", "opened_reason": "rule", "closed_reason": "approved", "open": false, "billing_zip": "string", "ip_address": "string", "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z" }, "refund": { "refund_id": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "created_at": "2026-06-15T14:30:00Z", "reason": "duplicate", "status": "pending", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available", "items": [ { "amount_refunded": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available" } ], "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "charge": { "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "amount_captured": 2500, "amount_refunded": 2500, "application_fee_amount": 0, "captured": false, "created_at": "2026-06-15T14:30:00Z", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_message": "Premium SPF 50 mineral sunscreen", "disputed": false, "paid": false, "refunded": false, "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "succeeded", "test_mode": false, "transfer_group": "example_value", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "three_d_secure": { "authentication_flow": "string", "result": "string", "result_reason": "string", "version": "string" }, "decline_details": { "failure_code": "string", "decline_code": "string", "failure_message": "string", "outcome_type": "string", "network_status": "string", "seller_message": "string", "reason": "string", "risk_level": "string" }, "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "export": { "export_id": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "type": "product", "status": "created", "created_at": "2026-06-15T14:30:00Z", "started_at": "2026-06-15T14:30:00Z", "completed_at": "2026-06-15T14:30:00Z", "metadata": { "order_id": "8842", "channel": "shopify" }, "filters": { "payment": { "limit": 0, "status": "canceled", "starting_after": "string", "ending_before": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "limit": 0, "offset": 0, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string", "start_date": "string", "end_date": "string" }, "subscription": { "limit": 0, "offset": 0, "start_date": "string", "end_date": "string" }, "customer": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "product": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "charge_reconciliation": { "start_date": "string", "end_date": "string" }, "payout": { "start_date": "string", "end_date": "string" }, "dispute": { "start_date": "string", "end_date": "string" }, "line_item": { "start_date": "string", "end_date": "string" }, "line_item_revenue": { "start_date": "string", "end_date": "string" }, "balance_activity": { "start_date": "string", "end_date": "string" } }, "test_mode": false }, "payment_method": { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "billing_details": { "address": { "city": "San Francisco", "country": "US", "line1": "123 Main St", "line2": "Suite 100", "postal_code": "94107", "state": "CA" }, "email": "john.doe@example.com", "name": "Example", "phone": "+14155550142" }, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "card": { "brand": "american_express", "country": "US", "exp_month": 12, "exp_year": 2027, "fingerprint": "abc123", "funding": "credit", "last4": "4242" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "off_session": true }, "product": { "product_id": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "document_description": "string", "receipt_description": "string", "created_at": "2026-06-15T14:30:00Z", "visit_type": "cbtSleep", "active": false, "upc_code": "string", "gtin": "string", "reference_gtin": "string", "hsa_fsa_eligibility": "not_eligible", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "balance_transaction": { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "available_on": "string", "created_at": "2026-06-15T14:30:00Z", "exchange_rate": 1.0, "fee": 2500, "net": 2500, "reporting_category": "example_value", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "available", "source_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "string", "flex_payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "mid": "example_value", "currency": "usd", "metadata": { "order_id": "8842", "channel": "shopify" }, "transaction_fee_amount": 0, "interchange_fee_amount": 0, "lmn_fee_amount": 0, "dispute_fee_amount": 0, "card_type": "string", "card_network": "string" } }, "test_mode": false, "created_at": "2026-06-15T14:30:00Z" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/checkout/sessions": { "get": { "tags": [ "Checkout Sessions" ], "summary": "List Checkout Sessions", "description": "Returns a list of your Checkout Sessions, most recent first.", "operationId": "v1.checkout_sessions.list", "parameters": [ { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int64", "minimum": 1.0, "maximum": 9007199254740991.0 }, "style": "form", "example": 10 }, { "in": "query", "name": "offset", "description": "Number of objects to skip before returning results.", "schema": { "description": "Number of objects to skip before returning results.", "examples": [ 3 ], "type": [ "integer", "null" ], "format": "int64", "maximum": 9007199254740991.0, "minimum": -9007199254740991.0 }, "style": "form", "example": 3 }, { "in": "query", "name": "interval", "description": "Filter by time interval in days (e.g., 30 for last 30 days).", "schema": { "description": "Filter by time interval in days (e.g., 30 for last 30 days).", "examples": [ 2500 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "style": "form", "example": 2500 }, { "in": "query", "name": "payment_intent", "description": "Filter by payment intent ID.", "schema": { "description": "Filter by payment intent ID.", "examples": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "status", "description": "Filter by checkout session status.", "schema": { "description": "Filter by checkout session status.", "anyOf": [ { "$ref": "#/components/schemas/Status" }, { "type": "null" } ] }, "style": "form" }, { "in": "query", "name": "customer", "description": "Filter by customer ID.", "schema": { "description": "Filter by customer ID.", "examples": [ "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "email", "description": "Filter results by customer email address.", "schema": { "description": "Filter results by customer email address.", "examples": [ "john.doe@example.com" ], "type": [ "string", "null" ], "format": "email" }, "style": "form", "example": "john.doe@example.com" }, { "in": "query", "name": "subscription", "description": "Filter by subscription ID.", "schema": { "description": "Filter by subscription ID.", "examples": [ "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "client_reference_id", "description": "Filter by the client reference ID you provided when creating the checkout session.", "schema": { "description": "Filter by the client reference ID you provided when creating the checkout session.", "examples": [ "example_value" ], "type": [ "string", "null" ] }, "style": "form", "example": "example_value" }, { "in": "query", "name": "expand_customer", "description": "If true, expands the customer object in the response.", "schema": { "description": "If true, expands the customer object in the response.", "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "query", "name": "expand_payment_intent", "description": "If true, expands the payment intent object in the response.", "schema": { "description": "If true, expands the payment intent object in the response.", "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response.", "schema": { "description": "Comma-separated list of related objects to expand in the response.", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" }, { "in": "query", "name": "created[gt]", "description": "Return sessions created after this timestamp (exclusive). ISO 8601 format.", "schema": { "description": "Return sessions created after this timestamp (exclusive). ISO 8601 format.", "default": null, "examples": [ "2026-06-15T14:30:00Z" ], "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "style": "form", "example": "2026-06-15T14:30:00Z" }, { "in": "query", "name": "created[gte]", "description": "Return sessions created at or after this timestamp (inclusive). ISO 8601 format.", "schema": { "description": "Return sessions created at or after this timestamp (inclusive). ISO 8601 format.", "default": null, "examples": [ "2026-06-15T14:30:00Z" ], "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "style": "form", "example": "2026-06-15T14:30:00Z" }, { "in": "query", "name": "created[lt]", "description": "Return sessions created before this timestamp (exclusive). ISO 8601 format.", "schema": { "description": "Return sessions created before this timestamp (exclusive). ISO 8601 format.", "default": null, "examples": [ "2026-06-15T14:30:00Z" ], "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "style": "form", "example": "2026-06-15T14:30:00Z" }, { "in": "query", "name": "created[lte]", "description": "Return sessions created at or before this timestamp (inclusive). ISO 8601 format.", "schema": { "description": "Return sessions created at or before this timestamp (inclusive). ISO 8601 format.", "default": null, "examples": [ "2026-06-15T14:30:00Z" ], "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "style": "form", "example": "2026-06-15T14:30:00Z" }, { "in": "query", "name": "starting_after", "description": "A cursor for use in pagination. `starting_after` is a checkout session ID that defines your place in the list. For instance, if you make a list request and receive 20 checkout sessions, ending with `fcs_xyz`, your subsequent call can include `starting_after=fcs_xyz` to fetch the next page.", "schema": { "description": "A cursor for use in pagination. `starting_after` is a checkout session ID that defines your place in the list. For instance, if you make a list request and receive 20 checkout sessions, ending with `fcs_xyz`, your subsequent call can include `starting_after=fcs_xyz` to fetch the next page.", "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "A cursor for use in pagination. `ending_before` is a checkout session ID that defines your place in the list. For instance, if you make a list request and receive 20 checkout sessions, starting with `fcs_abc`, your subsequent call can include `ending_before=fcs_abc` to fetch the previous page.", "schema": { "description": "A cursor for use in pagination. `ending_before` is a checkout session ID that defines your place in the list. For instance, if you make a list request and receive 20 checkout sessions, starting with `fcs_abc`, your subsequent call can include `ending_before=fcs_abc` to fetch the previous page.", "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "has_disputes", "description": "Return only checkout sessions with any associated dispute", "schema": { "description": "Return only checkout sessions with any associated dispute", "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "query", "name": "mode", "description": "Filter by checkout session mode.", "schema": { "description": "Filter by checkout session mode.", "anyOf": [ { "$ref": "#/components/schemas/Mode" }, { "type": "null" } ] }, "style": "form" }, { "in": "query", "name": "selling_plan", "description": "Filter by the Shopify selling plan the originating order was placed under, e.g. `gid://shopify/SellingPlan/123`.", "schema": { "description": "Filter by the Shopify selling plan the originating order was placed under, e.g. `gid://shopify/SellingPlan/123`.", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "description": "An envelope wrapping a list of checkout session objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleCheckoutSessionBody_for_CheckoutSession" }, "example": { "checkout_sessions": [ { "allow_promotion_codes": false, "amount_total": 2500, "amount_subtotal": 2500, "amount_received": 2500, "amount_refunded": 2500, "amount_disputed": 2500, "cancel_url": "https://example.com", "captures": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "disputes": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "capture_method": "automatic", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "example_value", "created_at": 2500, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "expires_at": 2500, "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "hsa_fsa_eligible": false, "letter_of_medical_necessity_required": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "mode": "payment", "origin": "shopify", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intents": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "redirect_url": "https://example.com", "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "shipping_address_collection": false, "shipping_details": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "open", "success_url": "https://example.com", "fees": [ { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } }, "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription_data": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "test_mode": false, "total_details": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "visit_type": "cbtSleep", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "next_action": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "selling_plans": [ { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } ], "shopify_payment_details": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } }, "renewal_as_of": 1781533800, "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "platform_fees": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "checkout_sessions:read" ] } ], "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } }, "post": { "tags": [ "Checkout Sessions" ], "summary": "Create Checkout Session", "description": "Creates a Checkout Session. The response includes a hosted `redirect_url` where the\ncustomer completes payment, along with the computed totals and eligibility. Flex\nclassifies the line items\nfor HSA/FSA eligibility and, when a Letter of Medical Necessity is required, sets up the\ncollection flow. The session's `mode` determines whether it results in a one-time\npayment, a subscription, an off-session charge against a saved payment method, or a\nsetup-only flow. When the line items mix eligible and non-eligible products, a split\ncart is created so each portion can be paid with the appropriate payment method.", "operationId": "v1.checkout_sessions.create", "requestBody": { "description": "An envelope wrapping a single checkout session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionBody_for_NewCheckoutSessionRequest" }, "example": { "checkout_session": { "allow_promotion_codes": false, "line_items": [ { "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } }, "quantity": 0, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "tax_rate": { "amount": 2500 }, "components": [ { "quantity": 1.0, "dressing_mode": "MIXED", "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string" } ] } ], "cancel_url": "https://example.com", "capture_method": "automatic", "client_reference_id": "example_value", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "discounts": [ { "coupon_id": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "promo_code_id": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "coupon_data": { "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "name": "Coupon", "amount_off": 100, "duration": "once", "percent_off": 10.0, "max_redemptions": 100, "metadata": { "key": "value" } } } ], "mode": "payment", "metadata": { "order_id": "8842", "channel": "shopify" }, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "shipping_address_collection": false, "subscription_data": { "trial_end": "2026-06-15T14:30:00Z", "cancel_at": "2026-06-15T14:30:00Z", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "success_url": "https://example.com", "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "string", "fees": [ { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "amount": 2500, "fee_type": "lmn_consultation" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": false, "payment": { "message": "Premium SPF 50 mineral sunscreen" } } } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single checkout session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionBody_for_CheckoutSession" }, "example": { "checkout_session": { "allow_promotion_codes": false, "amount_total": 2500, "amount_subtotal": 2500, "amount_received": 2500, "amount_refunded": 2500, "amount_disputed": 2500, "cancel_url": "https://example.com", "captures": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "disputes": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "capture_method": "automatic", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "example_value", "created_at": 2500, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "expires_at": 2500, "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "hsa_fsa_eligible": false, "letter_of_medical_necessity_required": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "mode": "payment", "origin": "shopify", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intents": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "redirect_url": "https://example.com", "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "shipping_address_collection": false, "shipping_details": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "open", "success_url": "https://example.com", "fees": [ { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } }, "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription_data": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "test_mode": false, "total_details": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "visit_type": "cbtSleep", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "next_action": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "selling_plans": [ { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } ], "shopify_payment_details": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } }, "renewal_as_of": 1781533800, "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "platform_fees": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "checkout_sessions:write" ] } ] } }, "/v1/checkout/sessions/{id}": { "get": { "tags": [ "Checkout Sessions" ], "summary": "Get Checkout Session", "description": "Retrieves the Checkout Session with the given ID. Use the `expand` parameters to inline\nrelated objects such as the customer, payment intent, or subscription in the response.", "operationId": "v1.checkout_sessions.get", "parameters": [ { "in": "query", "name": "expand_customer", "description": "If true, expands the customer object in the response.", "schema": { "description": "If true, expands the customer object in the response.", "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "query", "name": "expand_payment_intent", "description": "If true, expands the payment intent object in the response.", "schema": { "description": "If true, expands the payment intent object in the response.", "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "query", "name": "expand_subscription", "description": "If true, expands the subscription object in the response.", "schema": { "description": "If true, expands the subscription object in the response.", "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response.", "schema": { "description": "Comma-separated list of related objects to expand in the response.", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" }, { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single checkout session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionBody_for_CheckoutSession" }, "example": { "checkout_session": { "allow_promotion_codes": false, "amount_total": 2500, "amount_subtotal": 2500, "amount_received": 2500, "amount_refunded": 2500, "amount_disputed": 2500, "cancel_url": "https://example.com", "captures": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "disputes": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "capture_method": "automatic", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "example_value", "created_at": 2500, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "expires_at": 2500, "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "hsa_fsa_eligible": false, "letter_of_medical_necessity_required": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "mode": "payment", "origin": "shopify", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intents": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "redirect_url": "https://example.com", "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "shipping_address_collection": false, "shipping_details": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "open", "success_url": "https://example.com", "fees": [ { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } }, "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription_data": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "test_mode": false, "total_details": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "visit_type": "cbtSleep", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "next_action": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "selling_plans": [ { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } ], "shopify_payment_details": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } }, "renewal_as_of": 1781533800, "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "platform_fees": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "checkout_sessions:read" ] } ] } }, "/v1/checkout/sessions/{id}/line_items": { "get": { "tags": [ "Checkout Sessions" ], "summary": "Get Line Items", "description": "Returns the line items for the given Checkout Session. Each line item includes its\nprice, quantity, and computed amounts.", "operationId": "v1.line_items.list", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a list of line item objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleLineItemsBody_for_LineItem" }, "example": { "line_items": [ { "line_item_id": "fli_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount_discount": 2500, "amount_subtotal": 2500, "amount_tax": 2500, "amount_total": 2500, "amount_shipping": 2500, "amount_fee": 2500, "description": "Premium SPF 50 mineral sunscreen", "fees": [ { "fee_type": "lmn_consultation", "amount": 2500 } ], "price": { "price_id": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "trial_period_days": 0, "unit_amount": 0, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "active": false, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "type": "one_time", "metadata": { "order_id": "8842", "channel": "shopify" }, "lookup_key": "standard_monthly", "hsa_fsa_eligibility": "not_eligible", "test_mode": false }, "quantity": 2500, "eligibility": "not_eligible", "shipping_rate": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "checkout_sessions:read" ] } ] } }, "/v1/checkout/sessions/{id}/confirm": { "post": { "tags": [ "Checkout Sessions" ], "summary": "Confirm Checkout Session", "description": "Charges the HSA/FSA-eligible portion of a Checkout Session against a single saved payment\nmethod, using the eligibility split computed and persisted when the session was created. The\namount charged is the sum of the eligible portions of the session's items — never the session\ntotal — so `amount_received` is expected to be less than `amount_total`. Collect the remaining\nineligible balance through your own payment flow.\n\nReturns the Checkout Session with its `payment_intent` expanded. When the eligible portion sums\nto `$0`, or to less than Stripe's $0.50 minimum, nothing is charged and the response is still a\n`200` with `payment_intent: null` — a normal outcome for a partly-eligible order, not an error.\nBranch on `payment_intent == null` to decide whether there is anything to settle with Flex.\n\n`capture_method` must be `automatic`. `manual` is rejected with `manual_capture_not_supported`\n(422): it would authorize the card successfully and then be uncapturable, so it is refused\nbefore any money moves rather than leaving a hold to expire.\n\nAn `Idempotency-Key` header is **required**. Retry a timeout or a `5xx` with the same key; a new\nkey is a new request and can charge the card a second time. A `4xx` and a card decline are both\nterminal.\n\nError codes: `idempotency_key_required` (400), `checkout_session_already_processed` /\n`checkout_session_expired` / `checkout_session_canceled` (400),\n`checkout_session_not_found` / `payment_method_not_found` / `customer_not_found` /\n`eligibility_record_not_found` / `food_eligibility_not_enabled` (404),\n`eligibility_record_already_charged` / `idempotency_key_reused` (409),\n`manual_capture_not_supported` / `payment_method_not_off_session` (422),\n`idempotency_key_in_use` / `lock_timeout` (503 — transient contention: a request with this key\nis still in flight, or another request holds the customer or payment method. Retry unchanged\nwith the **same** key; a new key may charge the card twice), and a `402` carrying `code`\nand `decline_code` for a card decline — including `authentication_required`, which is terminal:\na card demanding 3DS cannot be charged off-session, so fall back to another tender rather than\nretrying.", "operationId": "v1.checkout_sessions.confirm", "parameters": [ { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response.", "schema": { "description": "Comma-separated list of related objects to expand in the response.", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" }, { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "header", "name": "Idempotency-Key", "description": "A unique key identifying this attempt. Retry a timed-out or `5xx` request with the SAME key — a new key is a new request and can charge the card a second time.", "required": true, "schema": { "type": "string" }, "style": "simple" } ], "requestBody": { "description": "An envelope wrapping a single checkout session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionBody_for_ConfirmCheckoutSessionRequest" }, "example": { "checkout_session": { "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "capture_method": "automatic" } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single checkout session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionBody_for_CheckoutSession" }, "example": { "checkout_session": { "allow_promotion_codes": false, "amount_total": 2500, "amount_subtotal": 2500, "amount_received": 2500, "amount_refunded": 2500, "amount_disputed": 2500, "cancel_url": "https://example.com", "captures": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "disputes": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "capture_method": "automatic", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "example_value", "created_at": 2500, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "expires_at": 2500, "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "hsa_fsa_eligible": false, "letter_of_medical_necessity_required": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "mode": "payment", "origin": "shopify", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intents": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "redirect_url": "https://example.com", "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "shipping_address_collection": false, "shipping_details": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "open", "success_url": "https://example.com", "fees": [ { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } }, "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription_data": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "test_mode": false, "total_details": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "visit_type": "cbtSleep", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "next_action": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "selling_plans": [ { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } ], "shopify_payment_details": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } }, "renewal_as_of": 1781533800, "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "platform_fees": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "checkout_sessions:write" ] } ] } }, "/v1/checkout/sessions/{id}/capture": { "post": { "tags": [ "Checkout Sessions" ], "summary": "Capture Checkout Session", "description": "Captures funds previously authorized on a Checkout Session whose payment intents use the\n`manual` capture method. Capture the full authorized amount, or a partial amount by\nspecifying `line_items` and component amounts (shipping, discount, tax). By default the\nremaining authorized amount stays available for further captures; set `final_capture` to\n`true` to release any uncaptured remainder. For split carts the capture is allocated\nacross the eligible and non-eligible payment intents; use the capture allocation preview\nendpoint to inspect the split first.", "operationId": "v1.checkout_sessions.capture", "parameters": [ { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response.", "schema": { "description": "Comma-separated list of related objects to expand in the response.", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" }, { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single checkout session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionBody_for_CaptureCheckoutSessionRequest" }, "example": { "checkout_session": { "final_capture": false, "line_items": [ { "amount_to_capture": 2500, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "metadata": { "order_id": "8842", "channel": "shopify" }, "capture_metadata": { "order_id": "8842", "channel": "shopify" }, "amount_shipping": 2500, "amount_discount": 2500, "amount_tax": 2500 } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single checkout session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionBody_for_CheckoutSession" }, "example": { "checkout_session": { "allow_promotion_codes": false, "amount_total": 2500, "amount_subtotal": 2500, "amount_received": 2500, "amount_refunded": 2500, "amount_disputed": 2500, "cancel_url": "https://example.com", "captures": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "disputes": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "capture_method": "automatic", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "example_value", "created_at": 2500, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "expires_at": 2500, "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "hsa_fsa_eligible": false, "letter_of_medical_necessity_required": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "mode": "payment", "origin": "shopify", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intents": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "redirect_url": "https://example.com", "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "shipping_address_collection": false, "shipping_details": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "open", "success_url": "https://example.com", "fees": [ { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } }, "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription_data": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "test_mode": false, "total_details": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "visit_type": "cbtSleep", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "next_action": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "selling_plans": [ { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } ], "shopify_payment_details": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } }, "renewal_as_of": 1781533800, "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "platform_fees": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "checkout_sessions:write" ] } ] } }, "/v1/checkout/sessions/{id}/capture_allocation": { "post": { "tags": [ "Checkout Sessions" ], "summary": "Preview Capture Allocation", "description": "Computes how a capture would be allocated across the Checkout Session's payment methods,\nwithout executing any capture. Takes the same request body as the capture endpoint and\nreturns the per-payment-method allocations so you can preview a split-cart capture before\ncommitting.", "operationId": "v1.checkout_sessions.preview_capture_allocation", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single checkout session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionBody_for_CaptureCheckoutSessionRequest" }, "example": { "checkout_session": { "final_capture": false, "line_items": [ { "amount_to_capture": 2500, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "metadata": { "order_id": "8842", "channel": "shopify" }, "capture_metadata": { "order_id": "8842", "channel": "shopify" }, "amount_shipping": 2500, "amount_discount": 2500, "amount_tax": 2500 } } } }, "required": true }, "responses": { "200": { "description": "Preview of how a capture would be distributed across the session's payment methods.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureAllocationResponse" }, "example": { "allocations": [ { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "last4": "4242", "amount": 2500 } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "checkout_sessions:write" ] } ] } }, "/v1/checkout/sessions/{id}/reauth": { "post": { "tags": [ "Checkout Sessions" ], "summary": "Reauth Checkout Session", "description": "Re-authorizes the payment on a Checkout Session whose authorization has expired or been\nfully captured, creating a new payment intent so the funds can be captured again. Use\n`amount_override` to authorize a different amount than the session total; otherwise the\nremaining authorizable amount is used. For split carts, the eligible and non-eligible\nbuckets are each re-authorized as needed.", "operationId": "v1.checkout_sessions.reauth", "parameters": [ { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response.", "schema": { "description": "Comma-separated list of related objects to expand in the response.", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" }, { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single checkout session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionBody_for_ReauthCheckoutSessionRequest" }, "example": { "checkout_session": { "amount_override": 2500 } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single checkout session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionBody_for_CheckoutSession" }, "example": { "checkout_session": { "allow_promotion_codes": false, "amount_total": 2500, "amount_subtotal": 2500, "amount_received": 2500, "amount_refunded": 2500, "amount_disputed": 2500, "cancel_url": "https://example.com", "captures": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "disputes": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "capture_method": "automatic", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "example_value", "created_at": 2500, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "expires_at": 2500, "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "hsa_fsa_eligible": false, "letter_of_medical_necessity_required": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "mode": "payment", "origin": "shopify", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intents": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "redirect_url": "https://example.com", "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "shipping_address_collection": false, "shipping_details": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "open", "success_url": "https://example.com", "fees": [ { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } }, "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription_data": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "test_mode": false, "total_details": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "visit_type": "cbtSleep", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "next_action": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "selling_plans": [ { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } ], "shopify_payment_details": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } }, "renewal_as_of": 1781533800, "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "platform_fees": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "checkout_sessions:write" ] } ] } }, "/v1/checkout/sessions/{id}/refund": { "post": { "tags": [ "Checkout Sessions" ], "summary": "Refund Checkout Session", "description": "Refunds a captured Checkout Session, in whole or in part. Refund a total `amount`,\nspecific `line_items`, or omit both to refund the full remaining amount; component\namounts (tax, shipping, discount) can be supplied for accurate allocation. For split\ncarts the refund is allocated across the eligible and non-eligible payment intents based\non HSA/FSA eligibility; the explicit `payment_methods` allocation is gated behind a\nbeta feature that must be enabled for your account. Use the refund allocation\npreview endpoint to inspect the split before refunding. A\n`checkout.session.refunded` event is emitted.", "operationId": "v1.checkout_sessions.refund", "parameters": [ { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response.", "schema": { "description": "Comma-separated list of related objects to expand in the response.", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" }, { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single checkout session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionBody_for_RefundCheckoutSessionRequest" }, "example": { "checkout_session": { "refund_metadata": { "order_id": "8842", "channel": "shopify" }, "amount_tax": 2500, "amount_shipping": 2500, "amount_discount": 2500, "payment_methods": [ { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500 } ], "line_items": [ { "amount_to_refund": 2500, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "amount": 0 } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single checkout session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionBody_for_CheckoutSession" }, "example": { "checkout_session": { "allow_promotion_codes": false, "amount_total": 2500, "amount_subtotal": 2500, "amount_received": 2500, "amount_refunded": 2500, "amount_disputed": 2500, "cancel_url": "https://example.com", "captures": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "disputes": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "capture_method": "automatic", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "example_value", "created_at": 2500, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "expires_at": 2500, "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "hsa_fsa_eligible": false, "letter_of_medical_necessity_required": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "mode": "payment", "origin": "shopify", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intents": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "redirect_url": "https://example.com", "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "shipping_address_collection": false, "shipping_details": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "open", "success_url": "https://example.com", "fees": [ { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } }, "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription_data": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "test_mode": false, "total_details": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "visit_type": "cbtSleep", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "next_action": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "selling_plans": [ { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } ], "shopify_payment_details": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } }, "renewal_as_of": 1781533800, "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "platform_fees": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "checkout_sessions:write" ] } ] } }, "/v1/checkout/sessions/{id}/refund_allocation": { "post": { "tags": [ "Checkout Sessions" ], "summary": "Preview Refund Allocation", "description": "Computes how a refund would be allocated across the Checkout Session's payment methods,\nwithout executing any refund. Takes the same request body as the refund endpoint and\nreturns the per-payment-method allocations so you can preview a split-cart refund before\ncommitting.", "operationId": "v1.checkout_sessions.preview_refund_allocation", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single checkout session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionBody_for_RefundCheckoutSessionRequest" }, "example": { "checkout_session": { "refund_metadata": { "order_id": "8842", "channel": "shopify" }, "amount_tax": 2500, "amount_shipping": 2500, "amount_discount": 2500, "payment_methods": [ { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500 } ], "line_items": [ { "amount_to_refund": 2500, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "amount": 0 } } } }, "required": true }, "responses": { "200": { "description": "Preview of how a refund would be distributed across the session's payment methods.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundAllocationResponse" }, "example": { "allocations": [ { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "last4": "4242", "amount": 2500 } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "checkout_sessions:write" ] } ] } }, "/v1/checkout/sessions/{id}/cancel": { "post": { "tags": [ "Checkout Sessions" ], "summary": "Cancel Auth Checkout Session", "description": "Cancels the authorization on a Checkout Session's payment intents, releasing the held\nfunds back to the customer. Only payment intents in a cancellable state are canceled;\nthe request fails with a 422 if the session has no payment intents or none are\ncancellable.", "operationId": "v1.checkout_sessions.cancel", "parameters": [ { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response.", "schema": { "description": "Comma-separated list of related objects to expand in the response.", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" }, { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single checkout session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionBody_for_CheckoutSession" }, "example": { "checkout_session": { "allow_promotion_codes": false, "amount_total": 2500, "amount_subtotal": 2500, "amount_received": 2500, "amount_refunded": 2500, "amount_disputed": 2500, "cancel_url": "https://example.com", "captures": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "disputes": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "capture_method": "automatic", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "example_value", "created_at": 2500, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "expires_at": 2500, "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "hsa_fsa_eligible": false, "letter_of_medical_necessity_required": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "mode": "payment", "origin": "shopify", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intents": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "redirect_url": "https://example.com", "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "shipping_address_collection": false, "shipping_details": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "open", "success_url": "https://example.com", "fees": [ { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } }, "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription_data": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "test_mode": false, "total_details": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "visit_type": "cbtSleep", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "next_action": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "selling_plans": [ { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } ], "shopify_payment_details": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } }, "renewal_as_of": 1781533800, "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "platform_fees": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "checkout_sessions:write" ] } ] } }, "/v1/checkout/sessions/{id}/receipts/resend": { "post": { "tags": [ "Checkout Sessions" ], "summary": "Resend Checkout Session Receipts", "description": "Resends existing receipt emails for a checkout session.\n\nLooks up all receipts associated with the checkout session's payment intents\nand enqueues them to be emailed to the customer. Does not regenerate the PDFs.", "operationId": "v1.checkout_session.receipts.resend", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "Response returned after queuing receipt emails for resending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendReceiptsResponse" }, "example": { "receipt_ids": [ "string" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "checkout_sessions:write" ] } ] } }, "/v1/checkout/sessions/{id}/lomn/resend": { "post": { "tags": [ "Checkout Sessions" ], "summary": "Resend Checkout Session Lomn", "description": "Resends existing LOMN (Letter of Medical Necessity) emails for a checkout session.\n\nLooks up all consultations associated with the checkout session that have a letter\nof medical necessity and enqueues them to be emailed to the customer.", "operationId": "v1.checkout_session.lomn.resend", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "Response returned after queuing Letter of Medical Necessity (LOMN) emails for resending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendLomnResponse" }, "example": { "consultation_ids": [ "string" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "checkout_sessions:write" ] } ] } }, "/v1/coupons": { "get": { "tags": [ "Coupons" ], "summary": "List Coupons", "description": "Returns a list of your coupons. Optionally filter by `name`.", "operationId": "v1.coupons.list", "parameters": [ { "in": "query", "name": "name", "description": "Filter coupons by name.", "schema": { "description": "Filter coupons by name.", "examples": [ "Example" ], "type": [ "string", "null" ] }, "style": "form", "example": "Example" } ], "responses": { "200": { "description": "An envelope wrapping a list of coupon objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleCouponsBody_for_V1Coupon" }, "example": { "coupons": [ { "coupon_id": "fcoup_1234567890", "amount_off": 2500, "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "duration": "once", "duration_in_months": 0, "metadata": { "order_id": "8842", "channel": "shopify" }, "name": "Example", "percent_off": 0.0, "max_redemptions": 0, "times_redeemed": 0, "valid": false, "created_at": "2026-06-15T14:30:00Z", "test_mode": false } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "coupons:read" ] } ] }, "post": { "tags": [ "Coupons" ], "summary": "Create Coupon", "description": "Creates a coupon. Exactly one of `amount_off` or `percent_off` must be provided; supplying\nboth, or neither, is rejected. When `duration` is `repeating`, `duration_in_months` is\nrequired.", "operationId": "v1.coupons.create", "requestBody": { "description": "An envelope wrapping a single coupon object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponBody_for_CreateCouponRequest" }, "example": { "coupon": { "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "name": "Coupon", "amount_off": 100, "duration": "once", "percent_off": 10.0, "max_redemptions": 100, "metadata": { "key": "value" } } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single coupon object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponBody_for_V1Coupon" }, "example": { "coupon": { "coupon_id": "fcoup_1234567890", "amount_off": 2500, "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "duration": "once", "duration_in_months": 0, "metadata": { "order_id": "8842", "channel": "shopify" }, "name": "Example", "percent_off": 0.0, "max_redemptions": 0, "times_redeemed": 0, "valid": false, "created_at": "2026-06-15T14:30:00Z", "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "coupons:write" ] } ] } }, "/v1/coupons/{id}": { "get": { "tags": [ "Coupons" ], "summary": "Get Coupon", "description": "Retrieves a coupon by its ID.", "operationId": "v1.coupons.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single coupon object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponBody_for_V1Coupon" }, "example": { "coupon": { "coupon_id": "fcoup_1234567890", "amount_off": 2500, "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "duration": "once", "duration_in_months": 0, "metadata": { "order_id": "8842", "channel": "shopify" }, "name": "Example", "percent_off": 0.0, "max_redemptions": 0, "times_redeemed": 0, "valid": false, "created_at": "2026-06-15T14:30:00Z", "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "coupons:read" ] } ] } }, "/v1/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "description": "Returns a list of your customers, sorted by ID in descending order (most recently created first). Deleted customers are excluded.", "operationId": "v1.customer.list", "parameters": [ { "in": "query", "name": "starting_after", "description": "A cursor for use in pagination. `starting_after` is a customer ID that defines your place in the list. For instance, if you make a list request and receive 20 customers, ending with `cus_xyz`, your subsequent call can include `starting_after=cus_xyz` to fetch the next page.", "schema": { "description": "A cursor for use in pagination. `starting_after` is a customer ID that defines your place in the list. For instance, if you make a list request and receive 20 customers, ending with `cus_xyz`, your subsequent call can include `starting_after=cus_xyz` to fetch the next page.", "examples": [ "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "A cursor for use in pagination. `ending_before` is a customer ID that defines your place in the list. For instance, if you make a list request and receive 20 customers, starting with `cus_abc`, your subsequent call can include `ending_before=cus_abc` to fetch the previous page.", "schema": { "description": "A cursor for use in pagination. `ending_before` is a customer ID that defines your place in the list. For instance, if you make a list request and receive 20 customers, starting with `cus_abc`, your subsequent call can include `ending_before=cus_abc` to fetch the previous page.", "examples": [ "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "style": "form", "example": 10 }, { "in": "query", "name": "offset", "description": "Number of objects to skip before returning results.", "schema": { "description": "Number of objects to skip before returning results.", "examples": [ 3 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "style": "form", "example": 3 }, { "in": "query", "name": "email", "description": "Filter results by customer email address.", "schema": { "description": "Filter results by customer email address.", "examples": [ "john.doe@example.com" ], "type": [ "string", "null" ], "format": "email" }, "style": "form", "example": "john.doe@example.com" } ], "responses": { "200": { "description": "An envelope wrapping a list of customer objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleCustomersBody_for_Customer" }, "example": { "customers": [ { "customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D", "owner_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "customers:read" ] } ], "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } }, "post": { "tags": [ "Customers" ], "summary": "Create or update a customer", "description": "Creates a customer. This endpoint upserts by email: if a customer with the same email already exists, that customer is updated with the supplied values instead of a new one being created. A `customer.created` webhook event is fired only when a new customer is created (not on update). If `checkout_session_id` is provided, the referenced checkout session is updated to reference this customer.", "operationId": "v1.customer.create", "requestBody": { "description": "An envelope wrapping a single customer object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBody_for_CreateCustomerRequest" }, "example": { "customer": { "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": "{\"key\": \"value\"}" } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single customer object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBody_for_Customer" }, "example": { "customer": { "customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D", "owner_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "customers:write" ] } ] } }, "/v1/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Retrieve a customer", "description": "Retrieves the details of one of your customers.", "operationId": "v1.customer.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "include_org", "description": "Resolve a customer owned by a sibling partner in the same organization (PII opt-in). Defaults to `false`; a customer owned by another partner returns `404` unless this is `true` and the caller shares an organization with the owner. The owner is named on the response's `owner_partner_id`, and a sibling-owned customer's `metadata` is returned as `null`.", "schema": { "description": "Resolve a customer owned by a sibling partner in the same organization (PII opt-in). Defaults to `false`; a customer owned by another partner returns `404` unless this is `true` and the caller shares an organization with the owner. The owner is named on the response's `owner_partner_id`, and a sibling-owned customer's `metadata` is returned as `null`.", "type": [ "boolean", "null" ] }, "style": "form" } ], "responses": { "200": { "description": "An envelope wrapping a single customer object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBody_for_Customer" }, "example": { "customer": { "customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D", "owner_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "customers:read" ] } ] }, "delete": { "tags": [ "Customers" ], "summary": "Delete a customer", "description": "Deletes the specified customer. This is a soft delete: the customer is marked as deleted and no longer appears in list or retrieve responses, but historical records that reference the customer (such as payment intents and checkout sessions) continue to resolve it.", "operationId": "v1.customer.delete", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single customer object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBody_for_DeletedCustomerResponse" }, "example": { "customer": { "customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D", "deleted": true } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "customers:write" ] } ] }, "patch": { "tags": [ "Customers" ], "summary": "Update a customer", "description": "Updates the specified customer. Only the fields you provide are changed; omitted fields are left unchanged.", "operationId": "v1.customer.update", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single customer object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBody_for_UpdateCustomerRequest" }, "example": { "customer": { "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "metadata": "{\"key\": \"value\"}" } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single customer object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBody_for_Customer" }, "example": { "customer": { "customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D", "owner_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "customers:write" ] } ] } }, "/v1/customers/{id}/payment_methods": { "get": { "tags": [ "Customers" ], "summary": "List a customer's payment methods", "description": "Returns a list of payment methods attached to the specified customer, sorted by ID in descending order (most recently created first).", "operationId": "v1.payment_methods.list", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "style": "form", "example": 10 }, { "in": "query", "name": "offset", "description": "Number of objects to skip before returning results.", "schema": { "description": "Number of objects to skip before returning results.", "examples": [ 3 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "style": "form", "example": 3 }, { "in": "query", "name": "include_org", "description": "Resolve payment methods for a customer owned by a sibling partner in the same organization (PII opt-in). Defaults to `false`; a sibling-owned customer returns `404` unless this is `true` and the caller shares an organization with the owner. A sibling-owned payment method's `metadata` is returned as `null`.", "schema": { "description": "Resolve payment methods for a customer owned by a sibling partner in the same organization (PII opt-in). Defaults to `false`; a sibling-owned customer returns `404` unless this is `true` and the caller shares an organization with the owner. A sibling-owned payment method's `metadata` is returned as `null`.", "type": [ "boolean", "null" ] }, "style": "form" } ], "responses": { "200": { "description": "An envelope wrapping a list of payment method objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiplePaymentMethodsBody_for_V1PaymentMethod" }, "example": { "payment_methods": [ { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "billing_details": { "address": { "city": "San Francisco", "country": "US", "line1": "123 Main St", "line2": "Suite 100", "postal_code": "94107", "state": "CA" }, "email": "john.doe@example.com", "name": "Example", "phone": "+14155550142" }, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "card": { "brand": "american_express", "country": "example_value", "exp_month": 12, "exp_year": 2027, "funding": "credit", "last4": "example_value" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "off_session": false } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "customers:read" ] } ] } }, "/v1/customers/{id}/payment_methods/{pm_id}": { "get": { "tags": [ "Customers" ], "summary": "Retrieve a customer's payment method", "description": "Retrieves a single payment method by ID for the specified customer.", "operationId": "v1.payment_methods.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "path", "name": "pm_id", "required": true, "schema": { "examples": [ "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "style": "form", "example": 10 }, { "in": "query", "name": "offset", "description": "Number of objects to skip before returning results.", "schema": { "description": "Number of objects to skip before returning results.", "examples": [ 3 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "style": "form", "example": 3 }, { "in": "query", "name": "include_org", "description": "Resolve payment methods for a customer owned by a sibling partner in the same organization (PII opt-in). Defaults to `false`; a sibling-owned customer returns `404` unless this is `true` and the caller shares an organization with the owner. A sibling-owned payment method's `metadata` is returned as `null`.", "schema": { "description": "Resolve payment methods for a customer owned by a sibling partner in the same organization (PII opt-in). Defaults to `false`; a sibling-owned customer returns `404` unless this is `true` and the caller shares an organization with the owner. A sibling-owned payment method's `metadata` is returned as `null`.", "type": [ "boolean", "null" ] }, "style": "form" } ], "responses": { "200": { "description": "An envelope wrapping a single payment method object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodBody_for_V1PaymentMethod" }, "example": { "payment_method": { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "billing_details": { "address": { "city": "San Francisco", "country": "US", "line1": "123 Main St", "line2": "Suite 100", "postal_code": "94107", "state": "CA" }, "email": "john.doe@example.com", "name": "Example", "phone": "+14155550142" }, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "card": { "brand": "american_express", "country": "example_value", "exp_month": 12, "exp_year": 2027, "funding": "credit", "last4": "example_value" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "off_session": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "customers:read" ] } ] } }, "/v1/exports": { "get": { "tags": [ "Exports" ], "summary": "List Exports", "description": "Returns a list of your exports, sorted with the most recently created exports first.", "operationId": "v1.exports.list", "parameters": [ { "in": "query", "name": "starting_after", "description": "A cursor for use in pagination. `starting_after` is an export ID that defines your place in the list.", "schema": { "description": "A cursor for use in pagination. `starting_after` is an export ID that defines your place in the list.", "examples": [ "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "A cursor for use in pagination. `ending_before` is an export ID that defines your place in the list.", "schema": { "description": "A cursor for use in pagination. `ending_before` is an export ID that defines your place in the list.", "examples": [ "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "style": "form", "example": 10 }, { "in": "query", "name": "offset", "description": "Number of objects to skip before returning results.", "schema": { "description": "Number of objects to skip before returning results.", "examples": [ 3 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "style": "form", "example": 3 } ], "responses": { "200": { "description": "An envelope wrapping a list of export objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleExportsBody_for_Export" }, "example": { "export": [ { "export_id": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "type": "product", "status": "created", "created_at": "2026-06-15T14:30:00Z", "started_at": "2026-06-15T14:30:00Z", "completed_at": "2026-06-15T14:30:00Z", "metadata": { "order_id": "8842", "channel": "shopify" }, "filters": { "payment": { "limit": 0, "status": "canceled", "starting_after": "string", "ending_before": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "limit": 0, "offset": 0, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string", "start_date": "string", "end_date": "string" }, "subscription": { "limit": 0, "offset": 0, "start_date": "string", "end_date": "string" }, "customer": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "product": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "charge_reconciliation": { "start_date": "string", "end_date": "string" }, "payout": { "start_date": "string", "end_date": "string" }, "dispute": { "start_date": "string", "end_date": "string" }, "line_item": { "start_date": "string", "end_date": "string" }, "line_item_revenue": { "start_date": "string", "end_date": "string" }, "balance_activity": { "start_date": "string", "end_date": "string" } }, "test_mode": false } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } }, "post": { "tags": [ "Exports" ], "summary": "Create Export", "description": "Creates an export and starts generating the requested CSV file asynchronously. The export is returned with status `created` and is then processed in the background; poll it until its `status` is `completed` before requesting a download URL.", "operationId": "v1.export.create", "requestBody": { "description": "An envelope wrapping a single export object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportBody_for_CreateExportRequest" }, "example": { "export": { "description": "Premium SPF 50 mineral sunscreen", "filters": { "payment": { "limit": 0, "status": "canceled", "starting_after": "string", "ending_before": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "limit": 0, "offset": 0, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string", "start_date": "string", "end_date": "string" }, "subscription": { "limit": 0, "offset": 0, "start_date": "string", "end_date": "string" }, "customer": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "product": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "charge_reconciliation": { "start_date": "string", "end_date": "string" }, "payout": { "start_date": "string", "end_date": "string" }, "dispute": { "start_date": "string", "end_date": "string" }, "line_item": { "start_date": "string", "end_date": "string" }, "line_item_revenue": { "start_date": "string", "end_date": "string" }, "balance_activity": { "start_date": "string", "end_date": "string" } }, "metadata": { "order_id": "8842", "channel": "shopify" }, "type": "product" } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single export object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportBody_for_Export" }, "example": { "export": { "export_id": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "type": "product", "status": "created", "created_at": "2026-06-15T14:30:00Z", "started_at": "2026-06-15T14:30:00Z", "completed_at": "2026-06-15T14:30:00Z", "metadata": { "order_id": "8842", "channel": "shopify" }, "filters": { "payment": { "limit": 0, "status": "canceled", "starting_after": "string", "ending_before": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "limit": 0, "offset": 0, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string", "start_date": "string", "end_date": "string" }, "subscription": { "limit": 0, "offset": 0, "start_date": "string", "end_date": "string" }, "customer": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "product": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "charge_reconciliation": { "start_date": "string", "end_date": "string" }, "payout": { "start_date": "string", "end_date": "string" }, "dispute": { "start_date": "string", "end_date": "string" }, "line_item": { "start_date": "string", "end_date": "string" }, "line_item_revenue": { "start_date": "string", "end_date": "string" }, "balance_activity": { "start_date": "string", "end_date": "string" } }, "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/exports/{id}": { "get": { "tags": [ "Exports" ], "summary": "Get Export", "description": "Retrieves the details of an existing export, including its current `status`. Supply the unique export ID returned when the export was created.", "operationId": "v1.export.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single export object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportBody_for_Export" }, "example": { "export": { "export_id": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "type": "product", "status": "created", "created_at": "2026-06-15T14:30:00Z", "started_at": "2026-06-15T14:30:00Z", "completed_at": "2026-06-15T14:30:00Z", "metadata": { "order_id": "8842", "channel": "shopify" }, "filters": { "payment": { "limit": 0, "status": "canceled", "starting_after": "string", "ending_before": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "limit": 0, "offset": 0, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string", "start_date": "string", "end_date": "string" }, "subscription": { "limit": 0, "offset": 0, "start_date": "string", "end_date": "string" }, "customer": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "product": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "charge_reconciliation": { "start_date": "string", "end_date": "string" }, "payout": { "start_date": "string", "end_date": "string" }, "dispute": { "start_date": "string", "end_date": "string" }, "line_item": { "start_date": "string", "end_date": "string" }, "line_item_revenue": { "start_date": "string", "end_date": "string" }, "balance_activity": { "start_date": "string", "end_date": "string" } }, "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/exports/{id}/cancel": { "post": { "tags": [ "Exports" ], "summary": "Cancel Export", "description": "Cancels an export, setting its `status` to `cancelled`. An export that has already `completed` cannot be cancelled; an already-cancelled export is returned unchanged.", "operationId": "v1.export.cancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single export object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportBody_for_Export" }, "example": { "export": { "export_id": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "type": "product", "status": "created", "created_at": "2026-06-15T14:30:00Z", "started_at": "2026-06-15T14:30:00Z", "completed_at": "2026-06-15T14:30:00Z", "metadata": { "order_id": "8842", "channel": "shopify" }, "filters": { "payment": { "limit": 0, "status": "canceled", "starting_after": "string", "ending_before": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "limit": 0, "offset": 0, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string", "start_date": "string", "end_date": "string" }, "subscription": { "limit": 0, "offset": 0, "start_date": "string", "end_date": "string" }, "customer": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "product": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "charge_reconciliation": { "start_date": "string", "end_date": "string" }, "payout": { "start_date": "string", "end_date": "string" }, "dispute": { "start_date": "string", "end_date": "string" }, "line_item": { "start_date": "string", "end_date": "string" }, "line_item_revenue": { "start_date": "string", "end_date": "string" }, "balance_activity": { "start_date": "string", "end_date": "string" } }, "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/exports/{id}/presigned_url": { "post": { "tags": [ "Exports" ], "summary": "Create Export Url", "description": "Generates a temporary, presigned URL for downloading the export's generated CSV file. The export must have a generated file available — typically once its `status` is `completed`. The returned URL expires after a short period, so request a fresh one when it lapses.", "operationId": "v1.export.create.presigned_url", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a presigned download URL for an export's generated file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresignedUrlBody_for_String" }, "example": { "url": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/invoices": { "get": { "tags": [ "Invoices" ], "summary": "List Invoices", "description": "List invoices", "operationId": "v1.invoices.list", "parameters": [ { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response.", "schema": { "description": "Comma-separated list of related objects to expand in the response.", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" }, { "in": "query", "name": "customer", "description": "Filter invoices by customer ID", "schema": { "description": "Filter invoices by customer ID", "examples": [ "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "starting_after", "description": "A cursor for use in pagination. `starting_after` is an invoice ID that defines your place in the list. For instance, if you make a list request and receive 20 invoices, ending with `fin_xyz`, your subsequent call can include `starting_after=fin_xyz` to fetch the next page.", "schema": { "description": "A cursor for use in pagination. `starting_after` is an invoice ID that defines your place in the list. For instance, if you make a list request and receive 20 invoices, ending with `fin_xyz`, your subsequent call can include `starting_after=fin_xyz` to fetch the next page.", "examples": [ "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "A cursor for use in pagination. `ending_before` is an invoice ID that defines your place in the list. For instance, if you make a list request and receive 20 invoices, starting with `fin_abc`, your subsequent call can include `ending_before=fin_abc` to fetch the previous page.", "schema": { "description": "A cursor for use in pagination. `ending_before` is an invoice ID that defines your place in the list. For instance, if you make a list request and receive 20 invoices, starting with `fin_abc`, your subsequent call can include `ending_before=fin_abc` to fetch the previous page.", "examples": [ "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.", "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 100.0, "minimum": 1.0 }, "style": "form", "example": 10 } ], "responses": { "200": { "description": "An envelope wrapping a list of invoice objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleInvoicesBody_for_Invoice" }, "example": { "invoices": [ { "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "total": 2500, "amount_due": 2500, "amount_paid": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "period_end": "string", "period_start": "string", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "paid_at": "string", "status": "draft", "collection_method": "charge_automatically", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "backup_charge_status": "pending" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } } }, "/v1/invoices/{id}": { "get": { "tags": [ "Invoices" ], "summary": "Get Invoice", "description": "Get an invoice by id", "operationId": "v1.invoices.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response.", "schema": { "description": "Comma-separated list of related objects to expand in the response.", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" } ], "responses": { "200": { "description": "An envelope wrapping a single invoice object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceBody_for_Invoice" }, "example": { "invoice": { "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "total": 2500, "amount_due": 2500, "amount_paid": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "period_end": "string", "period_start": "string", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "paid_at": "string", "status": "draft", "collection_method": "charge_automatically", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "backup_charge_status": "pending" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/invoices/{id}/mark_uncollectible": { "post": { "tags": [ "Invoices" ], "summary": "Mark Invoice Uncollectible", "description": "Mark an invoice as uncollectible. This writes off the invoice and stops automatic collection attempts. If it is the latest invoice of a `past_due` subscription, the subscription returns to `active`, so cancel the subscription to end it.", "operationId": "v1.invoices.mark_uncollectible", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single invoice object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceBody_for_Invoice" }, "example": { "invoice": { "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "total": 2500, "amount_due": 2500, "amount_paid": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "period_end": "string", "period_start": "string", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "paid_at": "string", "status": "draft", "collection_method": "charge_automatically", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "backup_charge_status": "pending" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/product_components": { "get": { "tags": [ "Products" ], "summary": "List Product Components", "description": "Returns the product components you have registered, newest first.\n\nOnly components you have recorded nutrition for are listed: the underlying name\ntable is shared across accounts, so listing it would return tens of thousands of\nrows that belong to nobody.\n\nResults are paginated — the default `limit` is 10, so reading back a full menu\ntakes several requests. Pass the last object's `component_nutrition_id` as\n`starting_after` to fetch the next page, and keep going until a page comes back\nshorter than your `limit`.\n\nRather than paging the whole catalogue to find one ingredient, filter it:\n`client_reference_id` returns the single component carrying your own identifier,\n`name` matches the shared component name case-insensitively, and `category` and\n`canonical_food_key` narrow by those fields. Metadata is filtered with\n`metadata[key]=value`, with multiple keys AND-ed. Filters combine with each other\nand with the pagination cursors.", "operationId": "v1.product_components.list", "parameters": [ { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "type": [ "integer", "null" ], "format": "int64", "maximum": 100.0, "minimum": 1.0 }, "style": "form" }, { "in": "query", "name": "offset", "description": "Number of objects to skip before returning results.", "schema": { "description": "Number of objects to skip before returning results.", "type": [ "integer", "null" ], "format": "int64", "minimum": 0.0, "maximum": 9007199254740991.0 }, "style": "form" }, { "in": "query", "name": "starting_after", "description": "A cursor for use in pagination. `starting_after` is a `component_nutrition_id` that defines your place in the list — pass the one from the last object of the previous page to fetch the next.", "schema": { "description": "A cursor for use in pagination. `starting_after` is a `component_nutrition_id` that defines your place in the list — pass the one from the last object of the previous page to fetch the next.", "examples": [ "fcn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fcn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "A cursor for use in pagination. `ending_before` is a `component_nutrition_id` that defines your place in the list.", "schema": { "description": "A cursor for use in pagination. `ending_before` is a `component_nutrition_id` that defines your place in the list.", "examples": [ "fcn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fcn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "client_reference_id", "description": "Only return the component carrying this `client_reference_id`. The value is unique within your account and mode, so this returns at most one component — it is the direct answer to \"have I registered this ingredient already?\".", "schema": { "description": "Only return the component carrying this `client_reference_id`. The value is unique within your account and mode, so this returns at most one component — it is the direct answer to \"have I registered this ingredient already?\".", "examples": [ "example_value" ], "type": [ "string", "null" ] }, "style": "form", "example": "example_value" }, { "in": "query", "name": "category", "description": "Only return components in this menu category.", "schema": { "description": "Only return components in this menu category.", "anyOf": [ { "$ref": "#/components/schemas/ComponentCategory" }, { "type": "null" } ] }, "style": "form" }, { "in": "query", "name": "canonical_food_key", "description": "Only return components carrying this price-book join key.", "schema": { "description": "Only return components carrying this price-book join key.", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "name", "description": "Only return components with this name, matched case-insensitively. Names are shared across accounts, so this is the dedupe lookup for a component you have no id for.", "schema": { "description": "Only return components with this name, matched case-insensitively. Names are shared across accounts, so this is the dedupe lookup for a component you have no id for.", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "metadata", "description": "Filter by metadata key-value pairs using bracket syntax. For example: `metadata[lookup_key]=premium-plan`. Multiple keys use AND logic.", "schema": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "lookup_key": "premium-plan" } }, "explode": true, "style": "deepObject", "example": { "lookup_key": "premium-plan" } } ], "responses": { "200": { "description": "An envelope wrapping a list of product component objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleProductComponentsBody_for_V1ProductComponent" }, "example": { "product_components": [ { "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "component_nutrition_id": "fcn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "string", "shared": true, "test_mode": true, "category": "string", "serving_size_g": 0.0, "nutrition": { "calories": 0.0, "total_fat_g": 0.0, "saturated_fat_g": 0.0, "trans_fat_g": 0.0, "carbohydrate_g": 0.0, "fiber_g": 0.0, "protein_g": 0.0, "sodium_mg": 0.0, "added_sugar_g": 0.0 }, "vegan": true, "gluten_free": true, "canonical_food_key": "string", "client_reference_id": "string", "metadata": {}, "created_at": "string", "updated_at": "string" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "products:read" ] } ], "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } }, "post": { "tags": [ "Products" ], "summary": "Create Product Component", "description": "Registers a product component (an ingredient) and returns it with an `fcomp_`\nidentifier you can attach to products.\n\nNutrient values are stored per 100 g of the component. Send `nutrition_basis:\n\"as_served\"` with a `serving_size_g` to have per-serving figures converted for\nyou. Component names are matched case-insensitively against a shared name table,\nso registering a name another account already registered returns that same\n`component_id` with your own nutrition attached.\n\n**Registering something you already have is a `409`.** That covers both ways it\nhappens: describing the same component twice in the same mode, and reusing a\n`client_reference_id` on a different component. Both mean the same thing —\nthis ingredient is already registered, `PATCH` it instead — so a menu sync can\ntreat `409` as \"switch to update\" without inspecting the message.\n\nPass a `client_reference_id` to carry your own identifier for the ingredient.\nIt is unique within your account and mode, which is what lets you look a\ncomponent back up with\n`GET /v1/product_components?client_reference_id=…` instead of paging your\ncatalogue. The same value may be used by another account, and by you in your\nother mode.", "operationId": "v1.product_components.create", "requestBody": { "description": "An envelope wrapping a single product component object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductComponentBody_for_CreateProductComponentRequest" }, "example": { "product_component": { "name": "string", "category": "base", "nutrition_basis": "per_100g", "serving_size_g": 0.0, "nutrition": { "calories": 0.0, "total_fat_g": 0.0, "saturated_fat_g": 0.0, "trans_fat_g": 0.0, "carbohydrate_g": 0.0, "fiber_g": 0.0, "protein_g": 0.0, "sodium_mg": 0.0, "added_sugar_g": 0.0 }, "vegan": true, "gluten_free": true, "canonical_food_key": "string", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" } } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single product component object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductComponentBody_for_V1ProductComponent" }, "example": { "product_component": { "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "component_nutrition_id": "fcn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "string", "shared": true, "test_mode": true, "category": "string", "serving_size_g": 0.0, "nutrition": { "calories": 0.0, "total_fat_g": 0.0, "saturated_fat_g": 0.0, "trans_fat_g": 0.0, "carbohydrate_g": 0.0, "fiber_g": 0.0, "protein_g": 0.0, "sodium_mg": 0.0, "added_sugar_g": 0.0 }, "vegan": true, "gluten_free": true, "canonical_food_key": "string", "client_reference_id": "string", "metadata": {}, "created_at": "string", "updated_at": "string" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "products:write" ] } ] } }, "/v1/product_components/{id}": { "get": { "tags": [ "Products" ], "summary": "Get Product Component", "description": "Retrieves one of your product components by its `fcomp_` identifier, with the\nnutrition you recorded for it. Nutrient values are per 100 g.\n\nA component you have not registered nutrition for is a 404, even when the name\nitself exists in Flex's shared component table.", "operationId": "v1.product_components.get", "parameters": [ { "in": "path", "name": "id", "description": "The component's `fcomp_` identifier.", "required": true, "schema": { "description": "The component's `fcomp_` identifier.", "examples": [ "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single product component object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductComponentBody_for_V1ProductComponent" }, "example": { "product_component": { "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "component_nutrition_id": "fcn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "string", "shared": true, "test_mode": true, "category": "string", "serving_size_g": 0.0, "nutrition": { "calories": 0.0, "total_fat_g": 0.0, "saturated_fat_g": 0.0, "trans_fat_g": 0.0, "carbohydrate_g": 0.0, "fiber_g": 0.0, "protein_g": 0.0, "sodium_mg": 0.0, "added_sugar_g": 0.0 }, "vegan": true, "gluten_free": true, "canonical_food_key": "string", "client_reference_id": "string", "metadata": {}, "created_at": "string", "updated_at": "string" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "products:read" ] } ] }, "patch": { "tags": [ "Products" ], "summary": "Update Product Component", "description": "Updates your nutrition for a product component. Only the fields you supply are\nchanged.\n\nThe component's `name` cannot be changed — the name row is shared with every\nother account that registered the same ingredient. Use `clear` to reset a value\nto \"not supplied\"; omitting a field means \"leave unchanged\", so omission cannot\nexpress erasure.\n\n`metadata` is the one field that merges rather than replaces: the keys you send\nare added or overwritten and the rest are left alone, so removing a key means\n`clear: [\"metadata\"]`. Moving a `client_reference_id` onto this component when\nanother of your components in this mode already carries that value returns\n`409`.", "operationId": "v1.product_components.update", "parameters": [ { "in": "path", "name": "id", "description": "The component's `fcomp_` identifier.", "required": true, "schema": { "description": "The component's `fcomp_` identifier.", "examples": [ "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single product component object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductComponentBody_for_UpdateProductComponentRequest" }, "example": { "product_component": { "category": "base", "nutrition_basis": "per_100g", "serving_size_g": 0.0, "nutrition": { "calories": 0.0, "total_fat_g": 0.0, "saturated_fat_g": 0.0, "trans_fat_g": 0.0, "carbohydrate_g": 0.0, "fiber_g": 0.0, "protein_g": 0.0, "sodium_mg": 0.0, "added_sugar_g": 0.0 }, "vegan": true, "gluten_free": true, "canonical_food_key": "string", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "clear": [ "serving_size_g" ] } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single product component object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductComponentBody_for_V1ProductComponent" }, "example": { "product_component": { "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "component_nutrition_id": "fcn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "string", "shared": true, "test_mode": true, "category": "string", "serving_size_g": 0.0, "nutrition": { "calories": 0.0, "total_fat_g": 0.0, "saturated_fat_g": 0.0, "trans_fat_g": 0.0, "carbohydrate_g": 0.0, "fiber_g": 0.0, "protein_g": 0.0, "sodium_mg": 0.0, "added_sugar_g": 0.0 }, "vegan": true, "gluten_free": true, "canonical_food_key": "string", "client_reference_id": "string", "metadata": {}, "created_at": "string", "updated_at": "string" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "products:write" ] } ] } }, "/v1/products": { "get": { "tags": [ "Products" ], "summary": "List Products", "description": "Returns a list of your products, sorted by creation date with the most recently created products appearing first. By default only active products are returned; pass `active=false` to list archived ones. You can also filter by `client_reference_id`, by a single `category`, or by metadata using `metadata[key]=value` query parameters. Category matching is case-insensitive and returns a product when it carries the supplied category, even if it carries additional categories.", "operationId": "v1.products.list", "parameters": [ { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "minimum": 1.0, "maximum": 2147483647.0 }, "style": "form", "example": 10 }, { "in": "query", "name": "offset", "description": "Number of objects to skip before returning results.", "schema": { "description": "Number of objects to skip before returning results.", "examples": [ 3 ], "type": [ "integer", "null" ], "format": "int32", "minimum": 0.0, "maximum": 2147483647.0 }, "style": "form", "example": 3 }, { "in": "query", "name": "starting_after", "description": "A cursor for use in pagination. `starting_after` is a product ID that defines your place in the list.", "schema": { "description": "A cursor for use in pagination. `starting_after` is a product ID that defines your place in the list.", "examples": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "A cursor for use in pagination. `ending_before` is a product ID that defines your place in the list.", "schema": { "description": "A cursor for use in pagination. `ending_before` is a product ID that defines your place in the list.", "examples": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "active", "description": "Only return products where `active` matches this value.", "schema": { "description": "Only return products where `active` matches this value.", "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "query", "name": "client_reference_id", "description": "Filter products by their client-provided product identifier.", "schema": { "description": "Filter products by their client-provided product identifier.", "examples": [ "example_value" ], "type": [ "string", "null" ] }, "style": "form", "example": "example_value" }, { "in": "query", "name": "category", "description": "Only return products carrying this category. Matching is case-insensitive.", "schema": { "description": "Only return products carrying this category. Matching is case-insensitive.", "examples": [ "example_value" ], "type": [ "string", "null" ] }, "style": "form", "example": "example_value" }, { "in": "query", "name": "metadata", "description": "Filter by metadata key-value pairs using bracket syntax. For example: `metadata[lookup_key]=premium-plan`. Multiple keys use AND logic.", "schema": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "lookup_key": "premium-plan" } }, "explode": true, "style": "deepObject", "example": { "lookup_key": "premium-plan" } } ], "responses": { "200": { "description": "An envelope wrapping a list of product objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleProductsBody_for_Product" }, "example": { "products": [ { "product_id": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "document_description": "string", "receipt_description": "string", "created_at": "2026-06-15T14:30:00Z", "visit_type": "cbtSleep", "active": false, "upc_code": "string", "gtin": "string", "reference_gtin": "string", "hsa_fsa_eligibility": "not_eligible", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "products:read" ] } ], "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } }, "post": { "tags": [ "Products" ], "summary": "Create Product", "description": "Creates a new product. Flex automatically determines the product's HSA/FSA eligibility from the supplied name, description, identifiers, and URL; if it can't be resolved synchronously, the product is created with eligibility pending and classification continues in the background, after which a `product.updated` event may fire. A `product.created` event is sent to your configured webhook endpoints on success.", "operationId": "v1.products.create", "requestBody": { "description": "An envelope wrapping a single product object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductBody_for_CreateProductRequest" }, "example": { "product": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single product object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductBody_for_Product" }, "example": { "product": { "product_id": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "document_description": "string", "receipt_description": "string", "created_at": "2026-06-15T14:30:00Z", "visit_type": "cbtSleep", "active": false, "upc_code": "string", "gtin": "string", "reference_gtin": "string", "hsa_fsa_eligibility": "not_eligible", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "products:write" ] } ] } }, "/v1/products/processing_status": { "get": { "tags": [ "Products" ], "summary": "Processing Status", "description": "Returns how many of the account's products are still awaiting automatic\nHSA/FSA eligibility classification, capped for bounded cost on very large\ncatalogs. Backs the dashboard \"Syncing products\" banner; clients derive any\ntime estimate from `pending_classification` themselves.", "operationId": "v1.products.processing_status", "responses": { "200": { "description": "Catalog-wide eligibility processing status for the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessingStatusBody" }, "example": { "pending_classification": 142, "pending_classification_capped": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "products:read" ] } ] } }, "/v1/products/{id}": { "get": { "tags": [ "Products" ], "summary": "Get Product", "description": "Retrieves a product by ID. Resolves your own products, and (if you belong to an organization) products owned by a sibling account.", "operationId": "v1.products.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single product object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductBody_for_Product" }, "example": { "product": { "product_id": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "document_description": "string", "receipt_description": "string", "created_at": "2026-06-15T14:30:00Z", "visit_type": "cbtSleep", "active": false, "upc_code": "string", "gtin": "string", "reference_gtin": "string", "hsa_fsa_eligibility": "not_eligible", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "products:read" ] } ] }, "patch": { "tags": [ "Products" ], "summary": "Update Product", "description": "Updates the specified product by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Updates never re-run HSA/FSA eligibility determination — eligibility is set when the product is created and only changes through review, so correcting a product's ingredients cannot silently flip its eligibility. Passing `categories` replaces the product's existing categories, and passing `component_items` replaces its components (an empty array removes them all). A `product.updated` event is sent to your configured webhook endpoints on success.", "operationId": "v1.products.update", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single product object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductBody_for_UpdateProductRequest" }, "example": { "product": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "active": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "categories": [ "string" ], "component_items": [ { "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ] } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single product object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductBody_for_Product" }, "example": { "product": { "product_id": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "document_description": "string", "receipt_description": "string", "created_at": "2026-06-15T14:30:00Z", "visit_type": "cbtSleep", "active": false, "upc_code": "string", "gtin": "string", "reference_gtin": "string", "hsa_fsa_eligibility": "not_eligible", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "products:write" ] } ] } }, "/v1/payment_intents": { "get": { "tags": [ "Payment Intents" ], "summary": "List Payment Intents", "description": "Returns a list of payment intents", "operationId": "v1.payment_intents.list", "parameters": [ { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response.", "schema": { "description": "Comma-separated list of related objects to expand in the response.", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" }, { "in": "query", "name": "expand_customer", "description": "If true, expands the customer object in the response.", "schema": { "description": "If true, expands the customer object in the response.", "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "query", "name": "customer", "description": "Filter by customer ID.", "schema": { "description": "Filter by customer ID.", "examples": [ "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "checkout_session", "description": "Filter by checkout session ID.", "schema": { "description": "Filter by checkout session ID.", "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "starting_after", "description": "A cursor for use in pagination. `starting_after` is a payment intent ID that defines your place in the list. For instance, if you make a list request and receive 20 payment intents, ending with `fpi_xyz`, your subsequent call can include `starting_after=fpi_xyz` to fetch the next page.", "schema": { "description": "A cursor for use in pagination. `starting_after` is a payment intent ID that defines your place in the list. For instance, if you make a list request and receive 20 payment intents, ending with `fpi_xyz`, your subsequent call can include `starting_after=fpi_xyz` to fetch the next page.", "examples": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "A cursor for use in pagination. `ending_before` is a payment intent ID that defines your place in the list. For instance, if you make a list request and receive 20 payment intents, starting with `fpi_abc`, your subsequent call can include `ending_before=fpi_abc` to fetch the previous page.", "schema": { "description": "A cursor for use in pagination. `ending_before` is a payment intent ID that defines your place in the list. For instance, if you make a list request and receive 20 payment intents, starting with `fpi_abc`, your subsequent call can include `ending_before=fpi_abc` to fetch the previous page.", "examples": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "style": "form", "example": 10 }, { "in": "query", "name": "offset", "description": "Number of objects to skip before returning results.", "schema": { "description": "Number of objects to skip before returning results.", "examples": [ 3 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "style": "form", "example": 3 } ], "responses": { "200": { "description": "An envelope wrapping a list of payment intent objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiplePaymentIntentsBody_for_PaymentIntent" }, "example": { "payment_intents": [ { "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "amount_capturable": 2500, "amount_received": 2500, "application_fee_amount": 0, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "transfer_data": { "amount": 2500, "destination": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "status": "canceled", "latest_charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "capture_method": "automatic", "client_secret": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "transfer_group": "example_value", "payment_card_type": "primary", "letter_fee_amount": 0, "transaction_fee": 0, "last_payment_error": { "type": "string", "code": "string", "decline_code": "string", "message": "string", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "payment_intents:read" ] } ], "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } } }, "/v1/payment_intents/{id}": { "get": { "tags": [ "Payment Intents" ], "summary": "Get Payment Intent", "description": "Retrieves the details of a PaymentIntent that has previously been created.", "operationId": "v1.payment_intents.get", "parameters": [ { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response.", "schema": { "description": "Comma-separated list of related objects to expand in the response.", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" }, { "in": "query", "name": "expand_customer", "description": "If true, expands the customer object in the response.", "schema": { "description": "If true, expands the customer object in the response.", "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single payment intent object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntentBody_for_PaymentIntent" }, "example": { "payment_intent": { "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "amount_capturable": 2500, "amount_received": 2500, "application_fee_amount": 0, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "transfer_data": { "amount": 2500, "destination": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "status": "canceled", "latest_charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "capture_method": "automatic", "client_secret": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "transfer_group": "example_value", "payment_card_type": "primary", "letter_fee_amount": 0, "transaction_fee": 0, "last_payment_error": { "type": "string", "code": "string", "decline_code": "string", "message": "string", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "payment_intents:read" ] } ] } }, "/v1/payment_intents/{id}/receipt": { "post": { "tags": [ "Payment Intents" ], "summary": "Send Receipt", "description": "Send a receipt to customer for the associated payment", "operationId": "v1.payment_intents.receipt", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "204": { "description": "no content" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "payment_intents:write" ] } ] } }, "/v1/payment_intents/{id}/cancel": { "post": { "tags": [ "Payment Intents" ], "summary": "Cancel Payment Intent", "description": "Cancels a PaymentIntent", "operationId": "v1.payment_intents.cancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single payment intent object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntentBody_for_PaymentIntent" }, "example": { "payment_intent": { "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "amount_capturable": 2500, "amount_received": 2500, "application_fee_amount": 0, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "transfer_data": { "amount": 2500, "destination": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "status": "canceled", "latest_charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "capture_method": "automatic", "client_secret": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "transfer_group": "example_value", "payment_card_type": "primary", "letter_fee_amount": 0, "transaction_fee": 0, "last_payment_error": { "type": "string", "code": "string", "decline_code": "string", "message": "string", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "payment_intents:write" ] } ] } }, "/v1/payment_links": { "get": { "tags": [ "Payment Links" ], "summary": "List Payment Links", "description": "Returns a list of your payment links. Only active links are returned; archived (inactive)\nlinks are omitted. Results are ordered by ID descending. Supports cursor pagination via\n`starting_after`/`ending_before`; `offset` is deprecated. Line items and discounts are not\nexpanded here — retrieve a single link to load them.", "operationId": "v1.payment_links.list", "parameters": [ { "in": "query", "name": "limit", "description": "Maximum number of payment links to return", "schema": { "description": "Maximum number of payment links to return", "default": null, "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "minimum": 1.0, "maximum": 2147483647.0 }, "style": "form", "example": 10 }, { "in": "query", "name": "offset", "description": "Number of payment links to skip (deprecated, use cursor pagination)", "schema": { "description": "Number of payment links to skip (deprecated, use cursor pagination)", "default": null, "examples": [ 3 ], "type": [ "integer", "null" ], "format": "int32", "minimum": 0.0, "maximum": 2147483647.0 }, "style": "form", "example": 3 }, { "in": "query", "name": "starting_after", "description": "Cursor for pagination - return payment links after this ID", "schema": { "description": "Cursor for pagination - return payment links after this ID", "default": null, "examples": [ "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "Cursor for pagination - return payment links before this ID", "schema": { "description": "Cursor for pagination - return payment links before this ID", "default": null, "examples": [ "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a list of payment link objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiplePaymentLinksBody_for_PaymentLink" }, "example": { "payment_links": [ { "payment_link_id": "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "label": "Example", "active": false, "line_items": [ { "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } }, "quantity": 0, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "tax_rate": { "amount": 2500 }, "components": [ { "quantity": 1.0, "dressing_mode": "MIXED", "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string" } ] } ], "allow_promotion_codes": false, "shipping_address_collection": false, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "created_at": "2026-06-15T14:30:00Z", "payment_intent_data": { "capture_method": "automatic", "metadata": { "order_id": "8842", "channel": "shopify" } }, "after_completion": { "type": "redirect", "hosted_confirmation": { "custom_message": "Premium SPF 50 mineral sunscreen" }, "redirect": { "url": "https://example.com" } }, "origin": "shopify", "tax_rate": { "amount": 2500 }, "discounts": [ "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_future_use": "on_session", "test_mode": false } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } }, "post": { "tags": [ "Payment Links" ], "summary": "Create Payment Link", "description": "Creates a payment link: a shareable URL that generates a checkout session each time a customer\nopens it. The mode is determined by `line_items` — it becomes `subscription` if any price is\nrecurring, otherwise `payment`; pass `mode=setup` to save a payment method without a charge\n(setup mode requires a `label` and empty `line_items`). Creating a link may create supporting\nobjects as a side effect: inline `price_data` provisions a Product and Price (in Stripe and\nFlex), inline shipping rate data creates a Shipping Rate, and inline `coupon_data` discounts\ncreate Coupons. Promotion codes are not accepted as discounts here — use coupon IDs or inline\ncoupon data.", "operationId": "v1.payment_links.create", "requestBody": { "description": "An envelope wrapping a single payment link object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkBody_for_CreatePaymentLink" }, "example": { "payment_link": { "line_items": [ { "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } }, "quantity": 0, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "tax_rate": { "amount": 2500 }, "components": [ { "quantity": 1.0, "dressing_mode": "MIXED", "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string" } ] } ], "label": "Example", "shipping_address_collection": false, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "metadata": { "order_id": "8842", "channel": "shopify" }, "payment_intent_data": { "capture_method": "automatic", "metadata": { "order_id": "8842", "channel": "shopify" } }, "after_completion": { "type": "redirect", "hosted_confirmation": { "custom_message": "Premium SPF 50 mineral sunscreen" }, "redirect": { "url": "https://example.com" } }, "allow_promotion_codes": false, "origin": "shopify", "tax_rate": { "amount": 2500 }, "discounts": [ { "coupon_id": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "promo_code_id": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "coupon_data": { "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "name": "Coupon", "amount_off": 100, "duration": "once", "percent_off": 10.0, "max_redemptions": 100, "metadata": { "key": "value" } } } ], "mode": "payment", "setup_future_use": "on_session" } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single payment link object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkBody_for_PaymentLink" }, "example": { "payment_link": { "payment_link_id": "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "label": "Example", "active": false, "line_items": [ { "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } }, "quantity": 0, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "tax_rate": { "amount": 2500 }, "components": [ { "quantity": 1.0, "dressing_mode": "MIXED", "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string" } ] } ], "allow_promotion_codes": false, "shipping_address_collection": false, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "created_at": "2026-06-15T14:30:00Z", "payment_intent_data": { "capture_method": "automatic", "metadata": { "order_id": "8842", "channel": "shopify" } }, "after_completion": { "type": "redirect", "hosted_confirmation": { "custom_message": "Premium SPF 50 mineral sunscreen" }, "redirect": { "url": "https://example.com" } }, "origin": "shopify", "tax_rate": { "amount": 2500 }, "discounts": [ "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_future_use": "on_session", "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/payment_links/{id}": { "get": { "tags": [ "Payment Links" ], "summary": "Get Payment Link", "description": "Retrieves the details of an existing payment link, including its line items and applied\ndiscounts. If the link has no label yet, one is generated from its first line item's product\nand persisted before the link is returned.", "operationId": "v1.payment_links.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single payment link object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkBody_for_PaymentLink" }, "example": { "payment_link": { "payment_link_id": "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "label": "Example", "active": false, "line_items": [ { "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } }, "quantity": 0, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "tax_rate": { "amount": 2500 }, "components": [ { "quantity": 1.0, "dressing_mode": "MIXED", "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string" } ] } ], "allow_promotion_codes": false, "shipping_address_collection": false, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "created_at": "2026-06-15T14:30:00Z", "payment_intent_data": { "capture_method": "automatic", "metadata": { "order_id": "8842", "channel": "shopify" } }, "after_completion": { "type": "redirect", "hosted_confirmation": { "custom_message": "Premium SPF 50 mineral sunscreen" }, "redirect": { "url": "https://example.com" } }, "origin": "shopify", "tax_rate": { "amount": 2500 }, "discounts": [ "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_future_use": "on_session", "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } }, "patch": { "tags": [ "Payment Links" ], "summary": "Update Payment Link", "description": "Updates an existing payment link. Only the supplied fields are changed; omitted fields are\nleft unchanged. The mutable fields are the label, the after-completion behavior, the active\nflag, and shipping address collection — line items, discounts, and other parameters are fixed\nonce the link is created. Set `active` to `false` to archive the link, which removes it from\nlist results and makes checkout session generation from the link return a 404. Set `active`\nback to `true` to restore it.", "operationId": "v1.payment_links.update", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single payment link object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkBody_for_UpdatePaymentLinkRequest" }, "example": { "payment_link": { "label": "Example", "after_completion": { "type": "redirect", "hosted_confirmation": { "custom_message": "Premium SPF 50 mineral sunscreen" }, "redirect": { "url": "https://example.com" } }, "active": false, "shipping_address_collection": false } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single payment link object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkBody_for_PaymentLink" }, "example": { "payment_link": { "payment_link_id": "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "label": "Example", "active": false, "line_items": [ { "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } }, "quantity": 0, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "tax_rate": { "amount": 2500 }, "components": [ { "quantity": 1.0, "dressing_mode": "MIXED", "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string" } ] } ], "allow_promotion_codes": false, "shipping_address_collection": false, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "created_at": "2026-06-15T14:30:00Z", "payment_intent_data": { "capture_method": "automatic", "metadata": { "order_id": "8842", "channel": "shopify" } }, "after_completion": { "type": "redirect", "hosted_confirmation": { "custom_message": "Premium SPF 50 mineral sunscreen" }, "redirect": { "url": "https://example.com" } }, "origin": "shopify", "tax_rate": { "amount": 2500 }, "discounts": [ "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_future_use": "on_session", "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/payouts": { "get": { "tags": [ "Payouts" ], "summary": "List Payouts", "description": "Returns a list of payouts.", "operationId": "v1.payouts.list", "parameters": [ { "in": "query", "name": "payout_id", "description": "Filter by a specific payout ID.", "schema": { "description": "Filter by a specific payout ID.", "examples": [ "fpo_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fpo_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "start_date", "description": "Filter payouts created after this date (ISO 8601 format: 2023-10-01T00:00:00Z).", "schema": { "description": "Filter payouts created after this date (ISO 8601 format: 2023-10-01T00:00:00Z).", "examples": [ "2026-06-15T14:30:00Z" ], "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "style": "form", "example": "2026-06-15T14:30:00Z" }, { "in": "query", "name": "end_date", "description": "Filter payouts created before this date (ISO 8601 format: 2023-10-01T00:00:00Z).", "schema": { "description": "Filter payouts created before this date (ISO 8601 format: 2023-10-01T00:00:00Z).", "examples": [ "2026-06-15T14:30:00Z" ], "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "style": "form", "example": "2026-06-15T14:30:00Z" }, { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "minimum": 1.0, "maximum": 2147483647.0 }, "style": "form", "example": 10 } ], "responses": { "200": { "description": "An envelope wrapping a list of payout objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiplePayoutsBody_for_Payout" }, "example": { "payouts": [ { "payout_id": "fpo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "in_transit", "amount": 2500, "arrival_date": "string", "created_at": "2026-06-15T14:30:00Z", "source_type": "string", "test_mode": false, "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "payouts:read" ] } ] } }, "/v1/prices": { "get": { "tags": [ "Prices" ], "summary": "List Prices", "description": "Returns a list of your prices, sorted by price ID in descending order (most recently created first). By default only active prices are returned; pass `active=false` to list archived ones, or filter to a single product with `product`. A price is also omitted when its parent product is archived, even if the price itself is active. Resolve prices by lookup key with `lookup_keys[]=standard_monthly&lookup_keys[]=pro_monthly` — up to 10 per request, matching any of them. You can separately filter by metadata using `metadata[key]=value` query parameters, for example `metadata[lookup_key]=premium-plan`. The two are independent: `lookup_keys` matches the price's own `lookup_key` field, while `metadata[lookup_key]` matches a key-value pair you set yourself, and a price can carry a different value in each.", "operationId": "v1.prices.list", "parameters": [ { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "default": null, "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "style": "form", "example": 10 }, { "in": "query", "name": "offset", "description": "Number of objects to skip before returning results.", "schema": { "description": "Number of objects to skip before returning results.", "default": null, "examples": [ 3 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "style": "form", "example": 3 }, { "in": "query", "name": "active", "description": "Only return prices where `active` matches this value.", "schema": { "description": "Only return prices where `active` matches this value.", "default": null, "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "query", "name": "product", "description": "Filter by product ID to return prices for a specific product.", "schema": { "description": "Filter by product ID to return prices for a specific product.", "default": null, "examples": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "expand_product", "description": "If true, expands the product object in the response.", "schema": { "description": "If true, expands the product object in the response.", "default": null, "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "query", "name": "starting_after", "description": "A cursor for use in pagination. `starting_after` is a price ID that defines your place in the list. For instance, if you make a list request and receive 20 prices, ending with `fprice_xyz`, your subsequent call can include `starting_after=fprice_xyz` to fetch the next page.", "schema": { "description": "A cursor for use in pagination. `starting_after` is a price ID that defines your place in the list. For instance, if you make a list request and receive 20 prices, ending with `fprice_xyz`, your subsequent call can include `starting_after=fprice_xyz` to fetch the next page.", "default": null, "examples": [ "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "A cursor for use in pagination. `ending_before` is a price ID that defines your place in the list. For instance, if you make a list request and receive 20 prices, starting with `fprice_abc`, your subsequent call can include `ending_before=fprice_abc` to fetch the previous page.", "schema": { "description": "A cursor for use in pagination. `ending_before` is a price ID that defines your place in the list. For instance, if you make a list request and receive 20 prices, starting with `fprice_abc`, your subsequent call can include `ending_before=fprice_abc` to fetch the previous page.", "default": null, "examples": [ "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "lookup_keys", "description": "Resolve prices by their `lookup_key`, up to 10 per request. A price matches if its key is any of the values given. Both bracket forms are accepted and equivalent: `?lookup_keys[]=a&lookup_keys[]=b` and `?lookup_keys[0]=a&lookup_keys[1]=b`. Commas are not separators, so a key containing one needs no escaping. Distinct from `metadata[lookup_key]`, which filters a key-value pair you set yourself.", "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "example": [ "standard_monthly", "pro_monthly" ] }, "explode": true, "style": "deepObject", "example": [ "standard_monthly", "pro_monthly" ] }, { "in": "query", "name": "metadata", "description": "Filter by metadata key-value pairs using bracket syntax. For example: `metadata[lookup_key]=premium-plan`. Multiple keys use AND logic.", "schema": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "lookup_key": "premium-plan" } }, "explode": true, "style": "deepObject", "example": { "lookup_key": "premium-plan" } } ], "responses": { "200": { "description": "An envelope wrapping a list of price objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiplePriceBody_for_Price" }, "example": { "prices": [ { "price_id": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "trial_period_days": 0, "unit_amount": 0, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "active": false, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "type": "one_time", "metadata": { "order_id": "8842", "channel": "shopify" }, "lookup_key": "standard_monthly", "hsa_fsa_eligibility": "not_eligible", "test_mode": false } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "prices:read" ] } ], "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } }, "post": { "tags": [ "Prices" ], "summary": "Create Price", "description": "Creates a new price. Supply `product` to attach the price to an existing product, or `product_data` to create a new product inline in the same request. A price is one-time unless you include `recurring`, in which case it bills on the given interval. Amounts are in the smallest currency unit (cents) and charged in USD. If HSA/FSA eligibility is not set on the price, the parent product's eligibility applies.", "operationId": "v1.prices.create", "requestBody": { "description": "An envelope wrapping a single price object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceBody_for_NewPriceRequest" }, "example": { "price": { "lookup_key": "standard_monthly", "transfer_lookup_key": true, "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single price object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceBody_for_Price" }, "example": { "price": { "price_id": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "trial_period_days": 0, "unit_amount": 0, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "active": false, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "type": "one_time", "metadata": { "order_id": "8842", "channel": "shopify" }, "lookup_key": "standard_monthly", "hsa_fsa_eligibility": "not_eligible", "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "prices:write" ] } ] } }, "/v1/prices/{id}": { "get": { "tags": [ "Prices" ], "summary": "Get Price", "description": "Retrieves the price with the given ID. Pass `expand_product=true` to inline the full Product object instead of just its ID. Resolves your own prices, and (if you belong to an organization) prices owned by a sibling account.", "operationId": "v1.prices.get", "parameters": [ { "in": "query", "name": "expand_product", "description": "If true, expands the product object in the response.", "schema": { "description": "If true, expands the product object in the response.", "default": null, "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single price object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceBody_for_Price" }, "example": { "price": { "price_id": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "trial_period_days": 0, "unit_amount": 0, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "active": false, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "type": "one_time", "metadata": { "order_id": "8842", "channel": "shopify" }, "lookup_key": "standard_monthly", "hsa_fsa_eligibility": "not_eligible", "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "prices:read" ] } ] }, "post": { "tags": [ "Prices" ], "summary": "Update Price", "description": "Updates the specified price by setting the values of the parameters passed. Any parameters not provided are left unchanged. Only `description`, `active` and `lookup_key` can be updated; the unit amount, currency, and recurring interval of a price are immutable. Setting `active` to `false` archives the price so it can no longer be used for new purchases. Send `lookup_key: null` to release the key, or pass `transfer_lookup_key` to take it from whichever price holds it.", "operationId": "v1.prices.update", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single price object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceBody_for_UpdatePrice" }, "example": { "price": { "description": "Premium SPF 50 mineral sunscreen", "active": false, "lookup_key": "standard_monthly", "transfer_lookup_key": false } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single price object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceBody_for_Price" }, "example": { "price": { "price_id": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "trial_period_days": 0, "unit_amount": 0, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "active": false, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "type": "one_time", "metadata": { "order_id": "8842", "channel": "shopify" }, "lookup_key": "standard_monthly", "hsa_fsa_eligibility": "not_eligible", "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "prices:write" ] } ] } }, "/v1/promo_codes": { "get": { "tags": [ "Promo Codes" ], "summary": "List Promo Codes", "description": "Returns a list of your promotion codes. Optionally filter by `active`.", "operationId": "v1.promo_codes.list", "parameters": [ { "in": "query", "name": "active", "description": "Specifies whether the promo code is currently active.", "schema": { "description": "Specifies whether the promo code is currently active.", "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false } ], "responses": { "200": { "description": "An envelope wrapping a list of promotion code objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiplePromoCodesBody_for_PromoCode" }, "example": { "promo_codes": [ { "promo_code_id": "fpromo_01HACM7FZ1084XB1GB6053VM0E", "code": "SUMMER2016", "coupon": { "coupon_id": "fcoup_1234567890", "amount_off": 100, "applies_to": null, "duration": "once", "duration_in_months": null, "metadata": { "key": "value" }, "name": "Coupon", "percent_off": 10.0, "max_redemptions": 100, "times_redeemed": 0, "valid": true, "created_at": "2024-05-17T14:59:21Z", "test_mode": true }, "max_redemptions": 100, "times_redeemed": 0, "created_at": "2024-05-17T14:59:21Z", "customer": "fcus_01HACM7FZ1084XB1GB6053VM0D", "active": true, "metadata": { "key": "value" }, "test_mode": false } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "promo_codes:read" ] } ] }, "post": { "tags": [ "Promo Codes" ], "summary": "Create Promo Code", "description": "Creates a promotion code referencing an existing coupon. If `code` is omitted, a unique\ncode is generated automatically. The supplied `code` must be unique across your promotion\ncodes.", "operationId": "v1.promo_codes.create", "requestBody": { "description": "An envelope wrapping a single promotion code object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCodeBody_for_CreatePromoCodeRequest" }, "example": { "promo_code": { "coupon_id": "fcoup_1234567890", "code": "SUMMER2016", "max_redemptions": 100, "customer": "fcus_01HACM7FZ1084XB1GB6053VM0D", "metadata": { "key": "value" } } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single promotion code object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCodeBody_for_PromoCode" }, "example": { "promo_code": { "promo_code_id": "fpromo_01HACM7FZ1084XB1GB6053VM0E", "code": "SUMMER2016", "coupon": { "coupon_id": "fcoup_1234567890", "amount_off": 100, "applies_to": null, "duration": "once", "duration_in_months": null, "metadata": { "key": "value" }, "name": "Coupon", "percent_off": 10.0, "max_redemptions": 100, "times_redeemed": 0, "valid": true, "created_at": "2024-05-17T14:59:21Z", "test_mode": true }, "max_redemptions": 100, "times_redeemed": 0, "created_at": "2024-05-17T14:59:21Z", "customer": "fcus_01HACM7FZ1084XB1GB6053VM0D", "active": true, "metadata": { "key": "value" }, "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "promo_codes:write" ] } ] } }, "/v1/promo_codes/{id}": { "get": { "tags": [ "Promo Codes" ], "summary": "Get Promo Code", "description": "Retrieves a promotion code by its ID.", "operationId": "v1.promo_codes.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single promotion code object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCodeBody_for_PromoCode" }, "example": { "promo_code": { "promo_code_id": "fpromo_01HACM7FZ1084XB1GB6053VM0E", "code": "SUMMER2016", "coupon": { "coupon_id": "fcoup_1234567890", "amount_off": 100, "applies_to": null, "duration": "once", "duration_in_months": null, "metadata": { "key": "value" }, "name": "Coupon", "percent_off": 10.0, "max_redemptions": 100, "times_redeemed": 0, "valid": true, "created_at": "2024-05-17T14:59:21Z", "test_mode": true }, "max_redemptions": 100, "times_redeemed": 0, "created_at": "2024-05-17T14:59:21Z", "customer": "fcus_01HACM7FZ1084XB1GB6053VM0D", "active": true, "metadata": { "key": "value" }, "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "promo_codes:read" ] } ] }, "post": { "tags": [ "Promo Codes" ], "summary": "Update Promo Code", "description": "Updates a promotion code by its ID. Only `active` and `metadata` can be modified; the\nreferenced coupon and the code are immutable.", "operationId": "v1.promo_codes.update", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single promotion code object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCodeBody_for_UpdatePromoCodeRequest" }, "example": { "promo_code": { "active": false, "metadata": { "key": "value" } } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single promotion code object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCodeBody_for_PromoCode" }, "example": { "promo_code": { "promo_code_id": "fpromo_01HACM7FZ1084XB1GB6053VM0E", "code": "SUMMER2016", "coupon": { "coupon_id": "fcoup_1234567890", "amount_off": 100, "applies_to": null, "duration": "once", "duration_in_months": null, "metadata": { "key": "value" }, "name": "Coupon", "percent_off": 10.0, "max_redemptions": 100, "times_redeemed": 0, "valid": true, "created_at": "2024-05-17T14:59:21Z", "test_mode": true }, "max_redemptions": 100, "times_redeemed": 0, "created_at": "2024-05-17T14:59:21Z", "customer": "fcus_01HACM7FZ1084XB1GB6053VM0D", "active": true, "metadata": { "key": "value" }, "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "promo_codes:write" ] } ] } }, "/v1/refunds": { "get": { "tags": [ "Refunds" ], "summary": "List Refunds", "description": "Returns a list of your refunds, most recent first.", "operationId": "v1.refunds.list", "parameters": [ { "in": "query", "name": "status", "description": "Filter by refund status.", "schema": { "description": "Filter by refund status.", "anyOf": [ { "$ref": "#/components/schemas/RefundStatus" }, { "type": "null" } ] }, "style": "form" }, { "in": "query", "name": "payment_intent", "description": "Filter by payment intent ID.", "schema": { "description": "Filter by payment intent ID.", "examples": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "checkout_session", "description": "Filter by checkout session ID.", "schema": { "description": "Filter by checkout session ID.", "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "starting_after", "description": "A cursor for use in pagination. `starting_after` is a refund ID that defines your place in the list. For instance, if you make a list request and receive 20 refunds, ending with `fre_xyz`, your subsequent call can include `starting_after=fre_xyz` to fetch the next page.", "schema": { "description": "A cursor for use in pagination. `starting_after` is a refund ID that defines your place in the list. For instance, if you make a list request and receive 20 refunds, ending with `fre_xyz`, your subsequent call can include `starting_after=fre_xyz` to fetch the next page.", "examples": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "A cursor for use in pagination. `ending_before` is a refund ID that defines your place in the list. For instance, if you make a list request and receive 20 refunds, starting with `fre_abc`, your subsequent call can include `ending_before=fre_abc` to fetch the previous page.", "schema": { "description": "A cursor for use in pagination. `ending_before` is a refund ID that defines your place in the list. For instance, if you make a list request and receive 20 refunds, starting with `fre_abc`, your subsequent call can include `ending_before=fre_abc` to fetch the previous page.", "examples": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.", "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 100.0, "minimum": 1.0 }, "style": "form", "example": 10 } ], "responses": { "200": { "description": "An envelope wrapping a list of refund objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleRefundsBody_for_Refund" }, "example": { "refunds": [ { "refund_id": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "created_at": "2026-06-15T14:30:00Z", "reason": "duplicate", "status": "pending", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available", "items": [ { "amount_refunded": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available" } ], "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "refunds:read" ] } ], "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } }, "post": { "tags": [ "Refunds" ], "summary": "Create Refund", "description": "Creates a refund for a previously succeeded payment intent and returns the resulting Refund.\n\nThe referenced payment intent must have a `succeeded` status. If `amount` is omitted, the full amount of the payment intent is refunded. A `refund.created` event is emitted, and the returned refund's `status` may still be `pending`; subsequent status changes are delivered via webhooks.", "operationId": "v1.refunds.create", "requestBody": { "description": "An envelope wrapping a single refund object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundBody_for_CreateRefund" }, "example": { "refund": { "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "reason": "duplicate", "metadata": { "order_id": "8842", "channel": "shopify" } } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single refund object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundBody_for_Refund" }, "example": { "refund": { "refund_id": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "created_at": "2026-06-15T14:30:00Z", "reason": "duplicate", "status": "pending", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available", "items": [ { "amount_refunded": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available" } ], "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "refunds:write" ] } ] } }, "/v1/refunds/{refund_id}": { "get": { "tags": [ "Refunds" ], "summary": "Get Refund", "description": "Retrieves the details of an existing refund by its ID.", "operationId": "v1.refunds.get", "parameters": [ { "in": "path", "name": "refund_id", "required": true, "schema": { "examples": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single refund object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundBody_for_Refund" }, "example": { "refund": { "refund_id": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "created_at": "2026-06-15T14:30:00Z", "reason": "duplicate", "status": "pending", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available", "items": [ { "amount_refunded": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available" } ], "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "refunds:read" ] } ] }, "patch": { "tags": [ "Refunds" ], "summary": "Update Refund", "description": "Updates the `reason` and/or `metadata` of an existing refund. Only these two fields can be changed; the refund amount, status, and associated payment cannot be modified after creation. Supplied metadata keys are merged into any existing metadata.", "operationId": "v1.refunds.update", "parameters": [ { "in": "path", "name": "refund_id", "required": true, "schema": { "examples": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single refund object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundBody_for_UpdateRefundRequest" }, "example": { "refund": { "reason": "duplicate", "metadata": { "order_id": "8842", "channel": "shopify" } } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single refund object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundBody_for_Refund" }, "example": { "refund": { "refund_id": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "created_at": "2026-06-15T14:30:00Z", "reason": "duplicate", "status": "pending", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available", "items": [ { "amount_refunded": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available" } ], "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "refunds:write" ] } ] } }, "/v1/reviews": { "get": { "tags": [ "Reviews" ], "summary": "List Reviews", "description": "Returns a list of your fraud reviews, newest-first.\n\nUse the `open` filter to focus on reviews that still need action.", "operationId": "v1.reviews.list", "parameters": [ { "in": "query", "name": "open", "description": "Filter by review state. `true` returns only open reviews, `false` returns only closed. Omit to return both.", "schema": { "description": "Filter by review state. `true` returns only open reviews, `false` returns only closed. Omit to return both.", "type": [ "boolean", "null" ] }, "style": "form" }, { "in": "query", "name": "charge_id", "description": "Filter to reviews on a specific charge.", "schema": { "description": "Filter to reviews on a specific charge.", "examples": [ "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "payment_intent_id", "description": "Filter to reviews on a specific payment intent.", "schema": { "description": "Filter to reviews on a specific payment intent.", "examples": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "client_reference_id", "description": "Filter by `client_reference_id` (matches your own identifier on the underlying checkout session, when present).", "schema": { "description": "Filter by `client_reference_id` (matches your own identifier on the underlying checkout session, when present).", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "starting_after", "description": "Cursor for forward pagination — review id from a previous page.", "schema": { "description": "Cursor for forward pagination — review id from a previous page.", "examples": [ "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "Cursor for backward pagination.", "schema": { "description": "Cursor for backward pagination.", "examples": [ "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "limit", "description": "Page size, between 1 and 100. Default 20.", "schema": { "description": "Page size, between 1 and 100. Default 20.", "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 100.0, "minimum": 1.0 }, "style": "form", "example": 10 } ], "responses": { "200": { "description": "An envelope wrapping a list of review objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleReviewsBody_for_Review" }, "example": { "reviews": [ { "review_id": "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reason": "rule", "opened_reason": "rule", "closed_reason": "approved", "open": false, "billing_zip": "string", "ip_address": "string", "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "reviews:read" ] } ], "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } } }, "/v1/reviews/{review_id}": { "get": { "tags": [ "Reviews" ], "summary": "Get Review", "description": "Retrieves the details of a fraud review.", "operationId": "v1.reviews.get", "parameters": [ { "in": "path", "name": "review_id", "required": true, "schema": { "examples": [ "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single review object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewBody_for_Review" }, "example": { "review": { "review_id": "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reason": "rule", "opened_reason": "rule", "closed_reason": "approved", "open": false, "billing_zip": "string", "ip_address": "string", "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "reviews:read" ] } ] } }, "/v1/subscriptions": { "get": { "tags": [ "Subscriptions" ], "summary": "List Subscriptions", "description": "Returns a list of your subscriptions, most recent first. Optionally filter by customer or\nstatus. Use `expand` (or `expand_customer`) to inline related objects such as the\ncustomer, latest invoice, item prices, or applied discounts.", "operationId": "v1.subscriptions.list", "parameters": [ { "in": "query", "name": "customer", "description": "Filter by customer ID.", "schema": { "description": "Filter by customer ID.", "examples": [ "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "expand_customer", "description": "If true, expands the customer object in the response.", "schema": { "description": "If true, expands the customer object in the response.", "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "query", "name": "starting_after", "description": "A cursor for use in pagination. `starting_after` is a subscription ID that defines your place in the list. For instance, if you make a list request and receive 20 subscriptions, ending with `fsub_xyz`, your subsequent call can include `starting_after=fsub_xyz` to fetch the next page.", "schema": { "description": "A cursor for use in pagination. `starting_after` is a subscription ID that defines your place in the list. For instance, if you make a list request and receive 20 subscriptions, ending with `fsub_xyz`, your subsequent call can include `starting_after=fsub_xyz` to fetch the next page.", "examples": [ "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "A cursor for use in pagination. `ending_before` is a subscription ID that defines your place in the list. For instance, if you make a list request and receive 20 subscriptions, starting with `fsub_abc`, your subsequent call can include `ending_before=fsub_abc` to fetch the previous page.", "schema": { "description": "A cursor for use in pagination. `ending_before` is a subscription ID that defines your place in the list. For instance, if you make a list request and receive 20 subscriptions, starting with `fsub_abc`, your subsequent call can include `ending_before=fsub_abc` to fetch the previous page.", "examples": [ "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "status", "description": "Filter by subscription status.", "schema": { "description": "Filter by subscription status.", "anyOf": [ { "$ref": "#/components/schemas/SubscriptionStatus" }, { "type": "null" } ] }, "style": "form" }, { "in": "query", "name": "offset", "description": "Number of objects to skip before returning results.", "schema": { "description": "Number of objects to skip before returning results.", "examples": [ 3 ], "type": [ "integer", "null" ], "format": "int32", "minimum": 0.0, "maximum": 2147483647.0 }, "style": "form", "example": 3 }, { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "minimum": 0.0, "maximum": 2147483647.0 }, "style": "form", "example": 10 }, { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response.\n\nSupported keys: `customer`; `latest_invoice` (alias `invoice`); `payment_method`; `backup_payment_method`; `price` (alias `product`); and `discounts`. Combine `discounts` with `coupons` (`expand=discounts,coupons`) to hydrate each discount's nested `source.coupon` into a full object instead of a bare ID.\n\nUnrecognized keys are ignored rather than rejected: a misspelled or guessed key (e.g. `coupon`) returns the same response as no `expand` at all, with no error.", "schema": { "description": "Comma-separated list of related objects to expand in the response.\n\nSupported keys: `customer`; `latest_invoice` (alias `invoice`); `payment_method`; `backup_payment_method`; `price` (alias `product`); and `discounts`. Combine `discounts` with `coupons` (`expand=discounts,coupons`) to hydrate each discount's nested `source.coupon` into a full object instead of a bare ID.\n\nUnrecognized keys are ignored rather than rejected: a misspelled or guessed key (e.g. `coupon`) returns the same response as no `expand` at all, with no error.", "default": "", "type": "string" }, "style": "form" } ], "responses": { "200": { "description": "An envelope wrapping a list of subscription objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleSubscriptionBody_for_Array_of_Subscription" }, "example": { "subscriptions": [ { "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "quantity": 2500, "created_at": "2026-06-15T14:30:00Z", "updated_at": "2026-06-15T14:30:00Z", "test_mode": false } ], "latest_invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "incomplete", "cancel_at_period_end": false, "current_period_end": "string", "current_period_start": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false, "client_secret": { "setup_secret": "string", "payment_secret": "string" }, "proration_behavior": "always_invoice", "trial_start": "string", "trial_end": "string", "cancel_at": "2026-06-15T14:30:00Z", "canceled_at": "2026-06-15T14:30:00Z", "default_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "discounts": [ { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } ], "pause": { "paused_at": "2026-06-15T14:30:00Z", "resume_at": "2026-06-15T14:30:00Z" } } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } } }, "/v1/subscriptions/{id}": { "get": { "tags": [ "Subscriptions" ], "summary": "Get Subscription", "description": "Retrieves the subscription with the given ID. Use `expand` (or `expand_customer`) to\ninline related objects such as the customer, latest invoice, default payment method,\nitem prices, or applied discounts.", "operationId": "v1.subscriptions.get", "parameters": [ { "in": "query", "name": "expand_customer", "description": "If true, expands the customer object in the response.", "schema": { "description": "If true, expands the customer object in the response.", "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response.\n\nSupported keys: `customer`; `latest_invoice` (alias `invoice`); `payment_method`; `backup_payment_method`; `price` (alias `product`); and `discounts`. Combine `discounts` with `coupons` (`expand=discounts,coupons`) to hydrate each discount's nested `source.coupon` into a full object instead of a bare ID.\n\nUnrecognized keys are ignored rather than rejected: a misspelled or guessed key (e.g. `coupon`) returns the same response as no `expand` at all, with no error.", "schema": { "description": "Comma-separated list of related objects to expand in the response.\n\nSupported keys: `customer`; `latest_invoice` (alias `invoice`); `payment_method`; `backup_payment_method`; `price` (alias `product`); and `discounts`. Combine `discounts` with `coupons` (`expand=discounts,coupons`) to hydrate each discount's nested `source.coupon` into a full object instead of a bare ID.\n\nUnrecognized keys are ignored rather than rejected: a misspelled or guessed key (e.g. `coupon`) returns the same response as no `expand` at all, with no error.", "default": "", "type": "string" }, "style": "form" }, { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single subscription object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionBody_for_Subscription" }, "example": { "subscription": { "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "quantity": 2500, "created_at": "2026-06-15T14:30:00Z", "updated_at": "2026-06-15T14:30:00Z", "test_mode": false } ], "latest_invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "incomplete", "cancel_at_period_end": false, "current_period_end": "string", "current_period_start": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false, "client_secret": { "setup_secret": "string", "payment_secret": "string" }, "proration_behavior": "always_invoice", "trial_start": "string", "trial_end": "string", "cancel_at": "2026-06-15T14:30:00Z", "canceled_at": "2026-06-15T14:30:00Z", "default_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "discounts": [ { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } ], "pause": { "paused_at": "2026-06-15T14:30:00Z", "resume_at": "2026-06-15T14:30:00Z" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } }, "delete": { "tags": [ "Subscriptions" ], "summary": "Cancel Subscription", "description": "Cancels a customer's subscription. By default the subscription is canceled immediately;\nset `cancel_at_period_end` to `true` to keep it active until the end of the current\nbilling period instead.\n\nOptionally issue a refund as part of the cancellation by setting `refund` to `full`,\n`prorated`, or `custom` (a `custom` refund requires a positive `refund_amount` in the\nsmallest currency unit). Refunds are processed as a separate operation from the\ncancellation. The request body is optional; omitting it cancels immediately with no\nrefund.", "operationId": "v1.subscriptions.cancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single subscription object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionBody_for_CancelSubscriptionRequest" }, "example": { "subscription": { "cancel_at_period_end": false, "refund": "none", "refund_amount": 2500 } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single subscription object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionBody_for_Subscription" }, "example": { "subscription": { "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "quantity": 2500, "created_at": "2026-06-15T14:30:00Z", "updated_at": "2026-06-15T14:30:00Z", "test_mode": false } ], "latest_invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "incomplete", "cancel_at_period_end": false, "current_period_end": "string", "current_period_start": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false, "client_secret": { "setup_secret": "string", "payment_secret": "string" }, "proration_behavior": "always_invoice", "trial_start": "string", "trial_end": "string", "cancel_at": "2026-06-15T14:30:00Z", "canceled_at": "2026-06-15T14:30:00Z", "default_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "discounts": [ { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } ], "pause": { "paused_at": "2026-06-15T14:30:00Z", "resume_at": "2026-06-15T14:30:00Z" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } }, "patch": { "tags": [ "Subscriptions" ], "summary": "Update Subscription", "description": "Updates an existing subscription. Any omitted field is left unchanged, and an empty\nrequest body is a no-op that simply returns the current subscription.\n\nThe change is first applied in Stripe and then mirrored to Flex, so the response\nreflects the resulting status and billing period. Updating `items` switches each item to\nthe supplied recurring price (or to a newly created price when `price_data` is given, in\nwhich case a new Price is created in Stripe and Flex); item prices must be recurring.\n`proration_behavior` controls how mid-cycle changes are prorated (`create_prorations` by\ndefault). Supplied `metadata` is merged into any existing metadata. Passing an empty\nstring for `coupon` removes the current coupon.", "operationId": "v1.subscriptions.update", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "expand_customer", "description": "If true, expands the customer object in the response.", "schema": { "description": "If true, expands the customer object in the response.", "examples": [ false ], "type": [ "boolean", "null" ] }, "style": "form", "example": false }, { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response.\n\nSupported keys: `customer`; `latest_invoice` (alias `invoice`); `payment_method`; `backup_payment_method`; `price` (alias `product`); and `discounts`. Combine `discounts` with `coupons` (`expand=discounts,coupons`) to hydrate each discount's nested `source.coupon` into a full object instead of a bare ID.\n\nUnrecognized keys are ignored rather than rejected: a misspelled or guessed key (e.g. `coupon`) returns the same response as no `expand` at all, with no error.", "schema": { "description": "Comma-separated list of related objects to expand in the response.\n\nSupported keys: `customer`; `latest_invoice` (alias `invoice`); `payment_method`; `backup_payment_method`; `price` (alias `product`); and `discounts`. Combine `discounts` with `coupons` (`expand=discounts,coupons`) to hydrate each discount's nested `source.coupon` into a full object instead of a bare ID.\n\nUnrecognized keys are ignored rather than rejected: a misspelled or guessed key (e.g. `coupon`) returns the same response as no `expand` at all, with no error.", "default": "", "type": "string" }, "style": "form" } ], "requestBody": { "description": "An envelope wrapping a single subscription object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionBody_for_UpdateSubscriptionRequest" }, "example": { "subscription": { "cancel_at_period_end": false, "trial_end": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } } } ], "proration_behavior": "always_invoice", "cancel_at": "2026-06-15T14:30:00Z", "metadata": { "order_id": "8842", "channel": "shopify" }, "coupon": "string", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single subscription object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionBody_for_Subscription" }, "example": { "subscription": { "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "quantity": 2500, "created_at": "2026-06-15T14:30:00Z", "updated_at": "2026-06-15T14:30:00Z", "test_mode": false } ], "latest_invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "incomplete", "cancel_at_period_end": false, "current_period_end": "string", "current_period_start": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false, "client_secret": { "setup_secret": "string", "payment_secret": "string" }, "proration_behavior": "always_invoice", "trial_start": "string", "trial_end": "string", "cancel_at": "2026-06-15T14:30:00Z", "canceled_at": "2026-06-15T14:30:00Z", "default_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "discounts": [ { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } ], "pause": { "paused_at": "2026-06-15T14:30:00Z", "resume_at": "2026-06-15T14:30:00Z" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/subscriptions/{id}/receipts/resend": { "post": { "tags": [ "Subscriptions" ], "summary": "Resend Subscription Receipts", "description": "Resends existing receipt emails for the initial checkout of a subscription.\n\nLooks up the receipts for the subscription's initial checkout-session payment and\nenqueues them to be emailed to the customer; the existing receipt PDFs are reused, not\nregenerated.", "operationId": "v1.subscription.receipts.resend", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "Response returned after queuing receipt emails for resending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendReceiptsResponse2" }, "example": { "receipt_ids": [ "string" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/subscriptions/{id}/refund_preview": { "get": { "tags": [ "Subscriptions" ], "summary": "Get Refund Preview", "description": "Previews the prorated refund that would result from canceling a subscription. Runs the\nsame validation as a real prorated refund but issues no refund and creates no records, so\nit is safe to call repeatedly. Returns the prorated amount available to refund, the amount\npaid on the latest invoice, the current billing period, and the card that would be\nrefunded.", "operationId": "v1.subscriptions.refund_preview", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "The result of previewing a prorated refund for a subscription cancellation, without issuing any refund. Reflects what would be refunded based on the remaining billing period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundPreviewResponse" }, "example": { "prorated_amount_available_to_refund": 2500, "invoice_amount_paid": 2500, "current_period_start": "2026-06-15T14:30:00Z", "current_period_end": "2026-06-15T14:30:00Z", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "last4": "4242" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/subscriptions/{id}/pause": { "post": { "tags": [ "Subscriptions" ], "summary": "Pause Subscription", "description": "Pauses an active subscription.\n\nNothing is invoiced while the subscription is paused, and its `current_period_end` shows\nthe pause date. The first pause moves the subscription to Stripe's flexible billing mode,\nwhich is permanent. The response carries the `pause` object immediately; the\n`customer.subscription.updated` event follows. A subscription that is already paused,\nnot active, scheduled to cancel, or still collecting its latest invoice is refused with a\ntyped error.", "operationId": "v1.subscriptions.pause", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "Options for pausing a subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PauseSubscriptionRequest" }, "example": { "resume_at": "2026-06-15T14:30:00Z" } } } }, "responses": { "200": { "description": "An envelope wrapping a single subscription object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionBody_for_Subscription" }, "example": { "subscription": { "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "quantity": 2500, "created_at": "2026-06-15T14:30:00Z", "updated_at": "2026-06-15T14:30:00Z", "test_mode": false } ], "latest_invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "incomplete", "cancel_at_period_end": false, "current_period_end": "string", "current_period_start": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false, "client_secret": { "setup_secret": "string", "payment_secret": "string" }, "proration_behavior": "always_invoice", "trial_start": "string", "trial_end": "string", "cancel_at": "2026-06-15T14:30:00Z", "canceled_at": "2026-06-15T14:30:00Z", "default_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "discounts": [ { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } ], "pause": { "paused_at": "2026-06-15T14:30:00Z", "resume_at": "2026-06-15T14:30:00Z" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/subscriptions/{id}/resume": { "post": { "tags": [ "Subscriptions" ], "summary": "Resume Subscription", "description": "Resumes a paused subscription.\n\nWith `billing_cycle_anchor: \"now\"` (the default) the full period is charged at once, net\nof the unused time credited at the pause, and billing restarts from today. With\n`\"unchanged\"` the original billing date is kept: the partial period is billed on that\ndate with the next full period, or, with `proration_behavior: \"always_invoice\"`, charged\nnow, net of the credit, with a negative amount going to the customer's balance.\n\nA declined charge returns a 402 naming the open invoice, and the subscription stays paused\nwhile that invoice is retried. Calling resume again pays that invoice rather than creating\na new one.\n\nRefusals carry a typed code: `subscription_pause_not_enabled` (422) when the account isn't\nin the rollout, `not_paused` (422) when the subscription isn't paused or a resume already\nhappened, `pause_in_progress` (409) while a pause request holds the subscription,\n`resume_in_progress` (409) while another resume does, `resume_invoice_not_open` (422) when\nan earlier resume's invoice is no longer payable, and\n`proration_behavior_requires_unchanged_anchor` (422) when `proration_behavior` is sent with\n`billing_cycle_anchor: \"now\"`.", "operationId": "v1.subscriptions.resume", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "Options for resuming a paused subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeSubscriptionRequest" }, "example": { "billing_cycle_anchor": "unchanged", "proration_behavior": "always_invoice" } } } }, "responses": { "200": { "description": "An envelope wrapping a single subscription object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionBody_for_Subscription" }, "example": { "subscription": { "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "quantity": 2500, "created_at": "2026-06-15T14:30:00Z", "updated_at": "2026-06-15T14:30:00Z", "test_mode": false } ], "latest_invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "incomplete", "cancel_at_period_end": false, "current_period_end": "string", "current_period_start": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false, "client_secret": { "setup_secret": "string", "payment_secret": "string" }, "proration_behavior": "always_invoice", "trial_start": "string", "trial_end": "string", "cancel_at": "2026-06-15T14:30:00Z", "canceled_at": "2026-06-15T14:30:00Z", "default_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "discounts": [ { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } ], "pause": { "paused_at": "2026-06-15T14:30:00Z", "resume_at": "2026-06-15T14:30:00Z" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/balance_transactions": { "get": { "tags": [ "Balance Transactions" ], "summary": "List Balance Transactions", "description": "Returns a list of Balance transactions.", "operationId": "v1.balance_transactions.list", "parameters": [ { "in": "query", "name": "balance_transaction_id", "description": "Filter by a specific balance transaction ID.", "schema": { "description": "Filter by a specific balance transaction ID.", "examples": [ "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "payout_id", "description": "Filter by payout ID to see transactions included in a specific payout.", "schema": { "description": "Filter by payout ID to see transactions included in a specific payout.", "examples": [ "fpo_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fpo_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "reporting_category", "description": "Filter by reporting category.", "schema": { "description": "Filter by reporting category.", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "type", "description": "Filter by transaction type.", "schema": { "description": "Filter by transaction type.", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "flex_payment_intent_id", "description": "Filter by Flex payment intent ID. Returns balance transactions linked to that payment intent.", "schema": { "description": "Filter by Flex payment intent ID. Returns balance transactions linked to that payment intent.", "examples": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "source_id", "description": "Filter by Flex source ID. Returns balance transactions whose source object is the given Flex charge, refund, or payout (e.g., `fch_…`).", "schema": { "description": "Filter by Flex source ID. Returns balance transactions whose source object is the given Flex charge, refund, or payout (e.g., `fch_…`).", "examples": [ "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "starting_after", "description": "A cursor for use in pagination. `starting_after` is a balance transaction ID that defines your place in the list. For instance, if you make a list request and receive 20 balance transactions, ending with `fbt_xyz`, your subsequent call can include `starting_after=fbt_xyz` to fetch the next page.", "schema": { "description": "A cursor for use in pagination. `starting_after` is a balance transaction ID that defines your place in the list. For instance, if you make a list request and receive 20 balance transactions, ending with `fbt_xyz`, your subsequent call can include `starting_after=fbt_xyz` to fetch the next page.", "examples": [ "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "A cursor for use in pagination. `ending_before` is a balance transaction ID that defines your place in the list. For instance, if you make a list request and receive 20 balance transactions, starting with `fbt_abc`, your subsequent call can include `ending_before=fbt_abc` to fetch the previous page.", "schema": { "description": "A cursor for use in pagination. `ending_before` is a balance transaction ID that defines your place in the list. For instance, if you make a list request and receive 20 balance transactions, starting with `fbt_abc`, your subsequent call can include `ending_before=fbt_abc` to fetch the previous page.", "examples": [ "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "minimum": 1.0, "maximum": 2147483647.0 }, "style": "form", "example": 10 } ], "responses": { "200": { "description": "An envelope wrapping a list of balance transaction objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleBalanceTransactionsBody_for_BalanceTransaction" }, "example": { "balance_transactions": [ { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "available_on": "string", "created_at": "2026-06-15T14:30:00Z", "exchange_rate": 1.0, "fee": 2500, "net": 2500, "reporting_category": "example_value", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "available", "source_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "string", "flex_payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "mid": "example_value", "currency": "usd", "metadata": { "order_id": "8842", "channel": "shopify" }, "transaction_fee_amount": 0, "interchange_fee_amount": 0, "lmn_fee_amount": 0, "dispute_fee_amount": 0, "card_type": "string", "card_network": "string" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "balance_transactions:read" ] } ], "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } } }, "/v1/setup_intents": { "get": { "tags": [ "Setup Intents" ], "summary": "List Setup Intents", "description": "Returns a list of SetupIntents, sorted by ID in descending order (most recent first).\n\nThe `client_secret` is not included on listed SetupIntents; retrieve a SetupIntent\nindividually to obtain it.", "operationId": "v1.setup_intent.list", "parameters": [ { "in": "query", "name": "limit", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "schema": { "description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.", "default": null, "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "style": "form", "example": 10 }, { "in": "query", "name": "offset", "description": "Number of objects to skip before returning results.", "schema": { "description": "Number of objects to skip before returning results.", "default": null, "examples": [ 3 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "style": "form", "example": 3 }, { "in": "query", "name": "customer", "description": "Filter by customer ID.", "schema": { "description": "Filter by customer ID.", "default": null, "examples": [ "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "starting_after", "description": "A cursor for use in pagination. `starting_after` is a setup intent ID that defines your place in the list. For instance, if you make a list request and receive 20 setup intents, ending with `fsi_xyz`, your subsequent call can include `starting_after=fsi_xyz` to fetch the next page.", "schema": { "description": "A cursor for use in pagination. `starting_after` is a setup intent ID that defines your place in the list. For instance, if you make a list request and receive 20 setup intents, ending with `fsi_xyz`, your subsequent call can include `starting_after=fsi_xyz` to fetch the next page.", "default": null, "examples": [ "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "description": "A cursor for use in pagination. `ending_before` is a setup intent ID that defines your place in the list. For instance, if you make a list request and receive 20 setup intents, starting with `fsi_abc`, your subsequent call can include `ending_before=fsi_abc` to fetch the previous page.", "schema": { "description": "A cursor for use in pagination. `ending_before` is a setup intent ID that defines your place in the list. For instance, if you make a list request and receive 20 setup intents, starting with `fsi_abc`, your subsequent call can include `ending_before=fsi_abc` to fetch the previous page.", "default": null, "examples": [ "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "expand", "description": "Comma-separated list of fields to expand (e.g., \"subscription\").", "schema": { "description": "Comma-separated list of fields to expand (e.g., \"subscription\").", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" } ], "responses": { "200": { "description": "An envelope wrapping a list of setup intent objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleSetupIntentsBody_for_SetupIntent" }, "example": { "setup_intents": [ { "setup_intent_id": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_secret": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "status": "requires_payment_method", "usage": "off_session", "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } }, "post": { "tags": [ "Setup Intents" ], "summary": "Create Setup Intent", "description": "Creates a SetupIntent to collect a customer's payment method details for future off-session use.\n\nA new SetupIntent is created on each call and starts in the `requires_payment_method` status; it\nis not an upsert. The response includes a `client_secret` that you use to confirm the SetupIntent\nand attach a payment method from your frontend.", "operationId": "v1.setup_intents.create", "requestBody": { "description": "An envelope wrapping a single setup intent object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupIntentBody_for_CreateSetupIntent" }, "example": { "setup_intent": { "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single setup intent object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupIntentBody_for_SetupIntent" }, "example": { "setup_intent": { "setup_intent_id": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_secret": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "status": "requires_payment_method", "usage": "off_session", "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/setup_intents/{id}": { "get": { "tags": [ "Setup Intents" ], "summary": "Get Setup Intent", "description": "Retrieves the details of an existing SetupIntent.\n\nThe response includes a fresh `client_secret` for confirming the SetupIntent from\nyour frontend. Pass `expand=subscription` to inline the associated Subscription, when one exists.", "operationId": "v1.setup_intent.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "expand", "description": "Comma-separated list of fields to expand (e.g., \"subscription\").", "schema": { "description": "Comma-separated list of fields to expand (e.g., \"subscription\").", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" } ], "responses": { "200": { "description": "SetupIntent response with expandable subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupIntentResponse" }, "example": { "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "setup_intent_id": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_secret": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "status": "requires_payment_method", "usage": "off_session", "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } } } }, "/v1/captures": { "get": { "tags": [ "Captures" ], "summary": "List captures", "description": "Returns a list of your captures. Optionally filter to a single checkout session with the `checkout_session` query parameter, and expand related objects (such as the payment intent) with `expand`.", "operationId": "v1.captures.list", "parameters": [ { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response (e.g., \"payment_intent\").", "schema": { "description": "Comma-separated list of related objects to expand in the response (e.g., \"payment_intent\").", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" }, { "in": "query", "name": "checkout_session", "description": "Filter captures by checkout session ID.", "schema": { "description": "Filter captures by checkout session ID.", "examples": [ "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a list of capture objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleCapturesBody_for_V1Capture" }, "example": { "captures": [ { "amount_captured": 2500, "amount_shipping_captured": 2500, "amount_discount_captured": 2500, "amount_tax_captured": 2500, "capture_id": "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "amount_captured": 2500, "capture_item_id": "fcapi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false } ], "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "captures:read" ] } ] } }, "/v1/captures/{capture_id}": { "get": { "tags": [ "Captures" ], "summary": "Retrieve a capture", "description": "Retrieves the details of a capture. Use the `expand` query parameter to inline related objects (such as the payment intent).", "operationId": "v1.captures.get", "parameters": [ { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response (e.g., \"payment_intent\").", "schema": { "description": "Comma-separated list of related objects to expand in the response (e.g., \"payment_intent\").", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" }, { "in": "path", "name": "capture_id", "required": true, "schema": { "examples": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single capture object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureBody_for_V1Capture" }, "example": { "capture": { "amount_captured": 2500, "amount_shipping_captured": 2500, "amount_discount_captured": 2500, "amount_tax_captured": 2500, "capture_id": "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "amount_captured": 2500, "capture_item_id": "fcapi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false } ], "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "captures:read" ] } ] }, "patch": { "tags": [ "Captures" ], "summary": "Update a capture", "description": "Updates the specified capture by setting the values of the fields you pass; only `metadata` can be changed. Other capture fields, including captured amounts, cannot be modified.", "operationId": "v1.captures.update", "parameters": [ { "in": "query", "name": "expand", "description": "Comma-separated list of related objects to expand in the response (e.g., \"payment_intent\").", "schema": { "description": "Comma-separated list of related objects to expand in the response (e.g., \"payment_intent\").", "default": "", "examples": [ "" ], "type": "string" }, "style": "form", "example": "" }, { "in": "path", "name": "capture_id", "required": true, "schema": { "examples": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "requestBody": { "description": "An envelope wrapping a single capture object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureBody_for_UpdateCaptureRequest" }, "example": { "capture": { "metadata": { "order_id": "8842", "channel": "shopify" } } } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single capture object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureBody_for_V1Capture" }, "example": { "capture": { "amount_captured": 2500, "amount_shipping_captured": 2500, "amount_discount_captured": 2500, "amount_tax_captured": 2500, "capture_id": "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "amount_captured": 2500, "capture_item_id": "fcapi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false } ], "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "captures:write" ] } ] } }, "/v1/files": { "get": { "tags": [ "Files" ], "summary": "List Files", "description": "Returns a list of your files, sorted by creation date with the most recently created files first. Pass `purpose` to filter to a single file purpose. Requires the `files_read` scope.", "operationId": "v1.files.list", "parameters": [ { "in": "query", "name": "purpose", "schema": { "anyOf": [ { "$ref": "#/components/schemas/FilePurpose" }, { "type": "null" } ] }, "style": "form" }, { "in": "query", "name": "limit", "schema": { "examples": [ 10 ], "type": [ "integer", "null" ], "format": "int32", "maximum": 100.0, "minimum": 1.0 }, "style": "form", "example": 10 }, { "in": "query", "name": "starting_after", "schema": { "examples": [ "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "in": "query", "name": "ending_before", "schema": { "examples": [ "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": [ "string", "null" ] }, "style": "form", "example": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a list of file objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleFilesBody" }, "example": { "files": [ { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "purpose": "account_requirement", "filename": "string", "size": 0, "type": "string", "created_at": "2026-06-15T14:30:00Z", "expires_at": "2026-06-15T14:30:00Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "files:read" ] } ], "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$[-1].id", "results": "$" } } }, "post": { "tags": [ "Files" ], "summary": "Create File", "description": "Uploads a file to Flex. The request must be a `multipart/form-data` upload containing a `file` part and a `purpose` part. The file must be a JPEG, PNG, or PDF no larger than 5 MB; PNGs using 16-bit depth or Adam7 interlacing are rejected. The uploaded file can then be referenced by ID elsewhere in the API, for example as evidence on a dispute. Requires the `files_write` scope.", "operationId": "v1.files.create", "requestBody": { "description": "Multipart file upload", "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateFileRequest" }, "example": { "purpose": "account_requirement", "file": "string" } } }, "required": true }, "responses": { "200": { "description": "An envelope wrapping a single file object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileBody" }, "example": { "file": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "purpose": "account_requirement", "filename": "string", "size": 0, "type": "string", "created_at": "2026-06-15T14:30:00Z", "expires_at": "2026-06-15T14:30:00Z" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "files:write" ] } ] } }, "/v1/files/{id}": { "get": { "tags": [ "Files" ], "summary": "Retrieve File", "description": "Retrieves the details of an existing file. Supply the unique file ID that was returned when the file was uploaded. Requires the `files_read` scope.", "operationId": "v1.files.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "examples": [ "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "type": "string" }, "style": "simple", "example": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "responses": { "200": { "description": "An envelope wrapping a single file object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileBody" }, "example": { "file": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "purpose": "account_requirement", "filename": "string", "size": 0, "type": "string", "created_at": "2026-06-15T14:30:00Z", "expires_at": "2026-06-15T14:30:00Z" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorOut" }, "example": { "code": "string", "detail": "string" } } } } }, "security": [ { "BearerAuth": [ "files:read" ] } ] } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Use a Bearer token to access this API." } }, "schemas": { "MultipleShippingRatesBody_for_V1ShippingRate": { "description": "An envelope wrapping a list of shipping rate objects.", "type": "object", "required": [ "shipping_rates" ], "properties": { "shipping_rates": { "description": "The list of shipping rates.", "type": "array", "items": { "$ref": "#/components/schemas/V1ShippingRate" } } }, "example": { "shipping_rates": [ { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "active": false, "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z" } ] } }, "V1ShippingRate": { "description": "A ShippingRate represents a fixed shipping cost you can apply to a checkout session. Each shipping rate is denominated in USD.", "type": "object", "required": [ "active", "amount", "created_at", "display_name", "shipping_rate_id" ], "properties": { "shipping_rate_id": { "description": "Unique identifier for the shipping rate.", "type": "string", "example": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "active": { "description": "Whether the shipping rate can be applied to new checkout sessions. Defaults to `true` on creation; set to `false` to archive it.", "type": "boolean", "example": false }, "display_name": { "description": "The name shown to the customer at checkout (e.g., `Standard Shipping`).", "type": "string", "example": "Example" }, "amount": { "description": "The shipping cost, in the smallest currency unit (e.g., `500` = $5.00 USD). Always in USD.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "metadata": { "description": "Set of key-value pairs you can attach to the shipping rate for storing additional structured information. Omitted when no metadata is set.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "created_at": { "description": "Time at which the shipping rate was created, as an RFC 3339 timestamp.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" } }, "example": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "active": false, "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z" } }, "Timestamptz": { "description": "A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`).", "type": "string", "example": "string" }, "HttpErrorOut": { "title": "HttpError", "description": "The error response returned when a request cannot be completed.", "type": "object", "required": [ "code", "detail" ], "properties": { "code": { "description": "A short machine-readable error code identifying the type of error.", "type": "string" }, "detail": { "description": "A human-readable explanation of what went wrong.", "type": "string" } }, "example": { "code": "string", "detail": "string" } }, "HTTPValidationError": { "description": "The error response returned when request validation fails (HTTP 422).", "type": "object", "required": [ "detail" ], "properties": { "detail": { "description": "The list of validation errors, one entry per invalid field.", "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" } } }, "example": { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } }, "ValidationErrorItem": { "description": "Validation errors have their own schema to provide context for invalid requests eg. mismatched types and out of bounds values. There may be any number of these per 422 UNPROCESSABLE ENTITY error.", "type": "object", "required": [ "loc", "msg", "type" ], "properties": { "loc": { "description": "The location as a [`Vec`] of [`String`]s -- often in the form `[\"body\", \"field_name\"]`, `[\"query\", \"field_name\"]`, etc. They may, however, be arbitarily deep.", "type": "array", "items": { "type": "string" } }, "msg": { "description": "The message accompanying the validation error item.", "type": "string" }, "type": { "description": "The type of error, often \"type_error\" or \"value_error\", but sometimes with more context like as \"value_error.number.not_ge\"", "type": "string" } }, "example": { "loc": [ "string" ], "msg": "string", "type": "string" } }, "ShippingRateBody_for_CreateShippingRateRequest": { "description": "An envelope wrapping a single shipping rate object.", "type": "object", "required": [ "shipping_rate" ], "properties": { "shipping_rate": { "description": "The shipping rate.", "$ref": "#/components/schemas/CreateShippingRateRequest" } }, "example": { "shipping_rate": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } } }, "CreateShippingRateRequest": { "description": "Parameters for creating a shipping rate.", "type": "object", "required": [ "amount", "display_name" ], "properties": { "display_name": { "description": "The name shown to the customer at checkout (e.g., `Standard Shipping`). Must be at least 2 characters.", "type": "string", "minLength": 2, "example": "Example" }, "amount": { "description": "The shipping cost, in the smallest currency unit (e.g., `500` = $5.00 USD). Charged in USD.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "metadata": { "description": "Set of key-value pairs you can attach to the shipping rate for storing additional structured information.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } } }, "example": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "ShippingRateBody_for_V1ShippingRate": { "description": "An envelope wrapping a single shipping rate object.", "type": "object", "required": [ "shipping_rate" ], "properties": { "shipping_rate": { "description": "The shipping rate.", "$ref": "#/components/schemas/V1ShippingRate" } }, "example": { "shipping_rate": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "active": false, "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z" } } }, "ShippingRateBody_for_UpdateShippingRateRequest": { "description": "An envelope wrapping a single shipping rate object.", "type": "object", "required": [ "shipping_rate" ], "properties": { "shipping_rate": { "description": "The shipping rate.", "$ref": "#/components/schemas/UpdateShippingRateRequest" } }, "example": { "shipping_rate": { "metadata": { "order_id": "8842", "channel": "shopify" }, "active": false } } }, "UpdateShippingRateRequest": { "description": "Parameters for updating a shipping rate.", "type": "object", "properties": { "metadata": { "description": "Replaces the set of key-value pairs attached to the shipping rate. Omitting this clears any existing metadata.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "active": { "description": "Whether the shipping rate can be applied to new checkout sessions. Set to `false` to archive it.", "type": [ "boolean", "null" ], "example": false } }, "example": { "metadata": { "order_id": "8842", "channel": "shopify" }, "active": false } }, "DisputeStatus": { "description": "The current status of a dispute.", "oneOf": [ { "type": "string", "enum": [ "lost", "needs_response", "under_review", "warning_closed", "warning_needs_response", "warning_under_review", "won" ] }, { "description": "The dispute was prevented before reaching the card network.", "type": "string", "enum": [ "prevented" ] } ], "example": "lost" }, "MultipleDisputesBody_for_Dispute": { "description": "An envelope wrapping a list of dispute objects.", "type": "object", "required": [ "disputes" ], "properties": { "disputes": { "description": "The list of disputes.", "type": "array", "items": { "$ref": "#/components/schemas/Dispute" } } }, "example": { "disputes": [ { "dispute_id": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "currency": "usd", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "status": "lost", "reason": "bank_cannot_process", "is_charge_refundable": false, "evidence": { "access_activity_log": "string", "customer_name": "string", "customer_email_address": "string", "customer_purchase_ip": "string", "billing_address": "string", "shipping_address": "string", "shipping_tracking_number": "string", "shipping_carrier": "string", "shipping_date": "string", "service_date": "string", "product_description": "string", "refund_policy_disclosure": "string", "refund_refusal_explanation": "string", "cancellation_policy_disclosure": "string", "cancellation_rebuttal": "string", "duplicate_charge_explanation": "string", "duplicate_charge_id": "string", "uncategorized_text": "string", "customer_communication": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "customer_signature": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "shipping_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "receipt": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "duplicate_charge_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "service_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "uncategorized_file": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "cancellation_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "refund_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" } }, "evidence_details": { "due_by": "2026-06-15T14:30:00Z", "has_evidence": false, "past_due": false, "submission_count": 3 }, "balance_transactions": [ { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "fee": 2500, "net": 2500, "status": "available", "type": "string", "reporting_category": "example_value", "category": "example_value", "created_at": "2026-06-15T14:30:00Z" } ], "payment_method_details": { "type": "string", "card": { "brand": "visa", "network_reason_code": "example_value" } }, "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ] } }, "Dispute": { "description": "A Dispute object represents a customer's challenge to a payment, raised through their card issuer or bank (also known as a chargeback). Use it to track the dispute's status, review the reason it was filed, and submit evidence to contest it.", "type": "object", "required": [ "amount", "created_at", "currency", "dispute_id", "is_charge_refundable", "metadata", "payment_intent_id", "reason", "status", "test_mode" ], "properties": { "dispute_id": { "description": "Unique identifier for the dispute, prefixed with `fdp_`.", "type": "string", "example": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "payment_intent_id": { "description": "ID of the PaymentIntent that was disputed.", "type": "string", "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session_id": { "description": "ID of the Checkout Session associated with the disputed payment. `null` if the payment was not created via a checkout session.", "type": [ "string", "null" ], "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "amount": { "description": "Disputed amount, in the smallest currency unit (e.g., `2500` = $25.00 USD). Usually the full amount of the disputed payment.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "currency": { "description": "Three-letter ISO currency code, in lowercase (e.g., `usd`).", "type": "string", "example": "usd" }, "charge_id": { "description": "ID of the Charge that was disputed. `null` if the originating charge could not be resolved.", "type": [ "string", "null" ], "example": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "metadata": { "description": "Set of key-value pairs attached to the dispute for storing additional structured information.", "type": "object", "example": { "order_id": "8842", "channel": "shopify" } }, "created_at": { "description": "Time at which the dispute was created, as an RFC 3339 date-time string.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "status": { "description": "The current status of the dispute. Evidence can only be submitted while the status is `needs_response` or `warning_needs_response`.", "$ref": "#/components/schemas/DisputeStatus" }, "reason": { "description": "Reason the dispute was filed, as reported by the card network.", "$ref": "#/components/schemas/DisputeReason" }, "is_charge_refundable": { "description": "Whether the disputed charge can still be refunded. Once a payment is disputed, refunding it is typically no longer possible.", "type": "boolean", "example": false }, "evidence": { "description": "Evidence collected to respond to the dispute. On the list endpoint this is included only when you pass `expand=evidence`; `null` when no evidence has been recorded.", "anyOf": [ { "$ref": "#/components/schemas/DisputeEvidenceResponse" }, { "type": "null" } ] }, "evidence_details": { "description": "Metadata about the evidence submission, including the response deadline and whether evidence has been submitted.", "anyOf": [ { "$ref": "#/components/schemas/EvidenceDetails" }, { "type": "null" } ] }, "balance_transactions": { "description": "Balance transactions that record the funds withdrawn and returned as the dispute progresses (e.g., the initial debit and any reversal). An empty array when there are none.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DisputeBalanceTransactionInfo" } }, "payment_method_details": { "description": "Details of the payment method that was disputed, such as the card brand and network reason code. `null` when no payment method details are available.", "anyOf": [ { "$ref": "#/components/schemas/DisputePaymentMethodDetails" }, { "type": "null" } ] }, "test_mode": { "description": "Whether the dispute was created in test mode. `true` for disputes created with test API keys.", "type": "boolean", "example": false }, "client_reference_id": { "description": "Your own identifier for the customer or payment this dispute relates to, copied from the originating payment.", "type": [ "string", "null" ], "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "example": { "dispute_id": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "currency": "usd", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "status": "lost", "reason": "bank_cannot_process", "is_charge_refundable": false, "evidence": { "access_activity_log": "string", "customer_name": "string", "customer_email_address": "string", "customer_purchase_ip": "string", "billing_address": "string", "shipping_address": "string", "shipping_tracking_number": "string", "shipping_carrier": "string", "shipping_date": "string", "service_date": "string", "product_description": "string", "refund_policy_disclosure": "string", "refund_refusal_explanation": "string", "cancellation_policy_disclosure": "string", "cancellation_rebuttal": "string", "duplicate_charge_explanation": "string", "duplicate_charge_id": "string", "uncategorized_text": "string", "customer_communication": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "customer_signature": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "shipping_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "receipt": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "duplicate_charge_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "service_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "uncategorized_file": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "cancellation_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "refund_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" } }, "evidence_details": { "due_by": "2026-06-15T14:30:00Z", "has_evidence": false, "past_due": false, "submission_count": 3 }, "balance_transactions": [ { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "fee": 2500, "net": 2500, "status": "available", "type": "string", "reporting_category": "example_value", "category": "example_value", "created_at": "2026-06-15T14:30:00Z" } ], "payment_method_details": { "type": "string", "card": { "brand": "visa", "network_reason_code": "example_value" } }, "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "DisputeReason": { "description": "The reason for the dispute, as reported by the card network.", "type": "string", "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "fraudulent", "general", "incorrect_account_details", "insufficient_funds", "noncompliant", "product_not_received", "product_unacceptable", "subscription_canceled", "unrecognized" ], "example": "bank_cannot_process" }, "DisputeEvidenceResponse": { "description": "Evidence collected to respond to a dispute, with file references resolved to Flex file IDs.", "type": "object", "properties": { "access_activity_log": { "description": "A description of the activity on the customer's account or the order, showing that they accessed or used the product or service.", "type": [ "string", "null" ] }, "customer_name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "customer_email_address": { "description": "The email address of the customer.", "type": [ "string", "null" ] }, "customer_purchase_ip": { "description": "The IP address from which the customer made the purchase.", "type": [ "string", "null" ] }, "billing_address": { "description": "The billing address provided by the customer.", "type": [ "string", "null" ] }, "shipping_address": { "description": "The address to which a physical product was shipped.", "type": [ "string", "null" ] }, "shipping_tracking_number": { "description": "The tracking number for a physical product shipped to the customer.", "type": [ "string", "null" ] }, "shipping_carrier": { "description": "The delivery service that shipped a physical product (e.g., `usps`, `fedex`).", "type": [ "string", "null" ] }, "shipping_date": { "description": "The date on which a physical product was shipped to the customer.", "type": [ "string", "null" ] }, "service_date": { "description": "The date on which the service was provided to the customer.", "type": [ "string", "null" ] }, "product_description": { "description": "A description of the product or service purchased and an explanation of why the customer's claim is unwarranted.", "type": [ "string", "null" ] }, "refund_policy_disclosure": { "description": "Your refund policy as shown to the customer.", "type": [ "string", "null" ] }, "refund_refusal_explanation": { "description": "An explanation of why the customer is not entitled to a refund.", "type": [ "string", "null" ] }, "cancellation_policy_disclosure": { "description": "Your cancellation policy as shown to the customer.", "type": [ "string", "null" ] }, "cancellation_rebuttal": { "description": "An explanation of how the customer was shown that the subscription or service was not canceled.", "type": [ "string", "null" ] }, "duplicate_charge_explanation": { "description": "An explanation of the difference between the disputed payment and the charge the customer believes is a duplicate.", "type": [ "string", "null" ] }, "duplicate_charge_id": { "description": "The ID of the charge the customer claims is a duplicate of the disputed charge.", "type": [ "string", "null" ] }, "uncategorized_text": { "description": "Any additional evidence as free-form text.", "type": [ "string", "null" ] }, "customer_communication": { "description": "File evidence of any communication with the customer, such as emails proving they received the product or service.", "anyOf": [ { "$ref": "#/components/schemas/EvidenceFileInfo" }, { "type": "null" } ] }, "customer_signature": { "description": "File evidence of the customer's signature, such as a proof of delivery signed by the customer.", "anyOf": [ { "$ref": "#/components/schemas/EvidenceFileInfo" }, { "type": "null" } ] }, "shipping_documentation": { "description": "File documentation showing that a physical product was shipped to the customer (e.g., a shipping label or carrier receipt).", "anyOf": [ { "$ref": "#/components/schemas/EvidenceFileInfo" }, { "type": "null" } ] }, "receipt": { "description": "File evidence of the receipt or message sent to the customer notifying them of the charge.", "anyOf": [ { "$ref": "#/components/schemas/EvidenceFileInfo" }, { "type": "null" } ] }, "duplicate_charge_documentation": { "description": "File documentation for the prior charge the customer claims is a duplicate.", "anyOf": [ { "$ref": "#/components/schemas/EvidenceFileInfo" }, { "type": "null" } ] }, "service_documentation": { "description": "File documentation showing that a service was provided to the customer.", "anyOf": [ { "$ref": "#/components/schemas/EvidenceFileInfo" }, { "type": "null" } ] }, "uncategorized_file": { "description": "Any additional file evidence that does not fit another category.", "anyOf": [ { "$ref": "#/components/schemas/EvidenceFileInfo" }, { "type": "null" } ] }, "cancellation_policy": { "description": "File evidence of your cancellation policy as shown to the customer.", "anyOf": [ { "$ref": "#/components/schemas/EvidenceFileInfo" }, { "type": "null" } ] }, "refund_policy": { "description": "File evidence of your refund policy as shown to the customer.", "anyOf": [ { "$ref": "#/components/schemas/EvidenceFileInfo" }, { "type": "null" } ] } }, "example": { "access_activity_log": "string", "customer_name": "string", "customer_email_address": "string", "customer_purchase_ip": "string", "billing_address": "string", "shipping_address": "string", "shipping_tracking_number": "string", "shipping_carrier": "string", "shipping_date": "string", "service_date": "string", "product_description": "string", "refund_policy_disclosure": "string", "refund_refusal_explanation": "string", "cancellation_policy_disclosure": "string", "cancellation_rebuttal": "string", "duplicate_charge_explanation": "string", "duplicate_charge_id": "string", "uncategorized_text": "string", "customer_communication": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "customer_signature": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "shipping_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "receipt": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "duplicate_charge_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "service_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "uncategorized_file": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "cancellation_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "refund_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" } } }, "EvidenceFileInfo": { "description": "A reference to a file attached as dispute evidence.", "type": "object", "properties": { "file_id": { "description": "The Flex file ID (e.g., `ffile_xxx`).", "type": [ "string", "null" ], "example": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "filename": { "description": "The original filename from upload.", "type": [ "string", "null" ] }, "stripe_file_id": { "description": "Underlying card-network file ID, present when the file could not be matched to a Flex file ID.", "type": [ "string", "null" ] } }, "example": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" } }, "EvidenceDetails": { "description": "Details about the evidence submission deadline and status.", "type": "object", "required": [ "has_evidence", "past_due", "submission_count" ], "properties": { "due_by": { "description": "Deadline for submitting evidence, as an RFC 3339 date-time string.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" }, "has_evidence": { "description": "Whether evidence has been submitted", "type": "boolean", "example": false }, "past_due": { "description": "Whether the evidence deadline has passed", "type": "boolean", "example": false }, "submission_count": { "description": "Number of times evidence has been submitted", "type": "integer", "format": "int32", "example": 3, "minimum": -2147483648.0, "maximum": 2147483647.0 } }, "example": { "due_by": "2026-06-15T14:30:00Z", "has_evidence": false, "past_due": false, "submission_count": 3 } }, "DisputeBalanceTransactionInfo": { "description": "A summary of a balance transaction associated with a dispute, recording how funds moved on your balance as the dispute progressed (for example the initial debit when the dispute was filed, or the reversal if it was won).", "type": "object", "required": [ "amount", "balance_transaction_id", "fee", "net", "status" ], "properties": { "balance_transaction_id": { "description": "ID of the balance transaction, prefixed with `fbtxn_`.", "type": "string", "example": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "amount": { "description": "Gross amount of the transaction, in the smallest currency unit (e.g., `2500` = $25.00 USD). Negative when funds are withdrawn from your balance.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "fee": { "description": "Fee applied to the transaction, in the smallest currency unit (e.g., `1500` = $15.00 USD). For a dispute, this is typically the dispute (chargeback) fee.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "net": { "description": "Net amount applied to your balance after fees, in the smallest currency unit (`net = amount - fee`).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "status": { "description": "Status of the balance transaction: `available` or `pending`.", "$ref": "#/components/schemas/BalanceTransactionStatus" }, "type": { "description": "The type of balance transaction (e.g., `adjustment`). `null` when not classified.", "type": [ "string", "null" ] }, "reporting_category": { "description": "The reporting category used to group the transaction in financial reports.", "type": [ "string", "null" ], "example": "example_value" }, "category": { "description": "The role this transaction plays within the dispute (e.g., the initial debit or a reversal). `null` when not categorized.", "type": [ "string", "null" ], "example": "example_value" }, "created_at": { "description": "Time at which the balance transaction was created, as an RFC 3339 date-time string. `null` when unavailable.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" } }, "example": { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "fee": 2500, "net": 2500, "status": "available", "type": "string", "reporting_category": "example_value", "category": "example_value", "created_at": "2026-06-15T14:30:00Z" } }, "BalanceTransactionStatus": { "type": "string", "enum": [ "available", "pending" ], "x-ms-enum": { "name": "BalanceTransactionStatus", "modelAsString": false, "values": [ { "value": "available", "name": "Available", "description": "Funds have settled and are available to be paid out." }, { "value": "pending", "name": "Pending", "description": "Funds are not yet available." } ] }, "description": "Availability status of the funds in a balance transaction.\n\n- `available`: Funds have settled and are available to be paid out.\n- `pending`: Funds are not yet available.", "example": "available" }, "DisputePaymentMethodDetails": { "description": "Details of the payment method that was disputed.", "type": "object", "required": [ "type" ], "properties": { "type": { "description": "The type of payment method that was disputed (e.g., `card`).", "type": "string" }, "card": { "description": "Card-specific details, present when `type` is `card`. `null` for other payment method types.", "anyOf": [ { "$ref": "#/components/schemas/DisputePaymentMethodCard" }, { "type": "null" } ] } }, "example": { "type": "string", "card": { "brand": "visa", "network_reason_code": "example_value" } } }, "DisputePaymentMethodCard": { "description": "Card-specific details for a disputed payment made with a card.", "type": "object", "properties": { "brand": { "description": "The card brand. `null` when unknown.", "type": [ "string", "null" ], "example": "visa" }, "network_reason_code": { "description": "The reason code the card network assigned to the dispute, as reported by the issuer.", "type": [ "string", "null" ], "example": "example_value" } }, "example": { "brand": "visa", "network_reason_code": "example_value" } }, "DisputeCountBody": { "description": "The number of disputes that currently require a response.", "type": "object", "required": [ "count" ], "properties": { "count": { "description": "Count of disputes in a `needs_response` or `warning_needs_response` status.", "type": "integer", "format": "int64", "example": 3, "minimum": -9007199254740991.0, "maximum": 9007199254740991.0 } }, "example": { "count": 3 } }, "DisputeBody_for_Dispute": { "description": "An envelope wrapping a single dispute object.", "type": "object", "required": [ "dispute" ], "properties": { "dispute": { "description": "The dispute.", "$ref": "#/components/schemas/Dispute" } }, "example": { "dispute": { "dispute_id": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "currency": "usd", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "status": "lost", "reason": "bank_cannot_process", "is_charge_refundable": false, "evidence": { "access_activity_log": "string", "customer_name": "string", "customer_email_address": "string", "customer_purchase_ip": "string", "billing_address": "string", "shipping_address": "string", "shipping_tracking_number": "string", "shipping_carrier": "string", "shipping_date": "string", "service_date": "string", "product_description": "string", "refund_policy_disclosure": "string", "refund_refusal_explanation": "string", "cancellation_policy_disclosure": "string", "cancellation_rebuttal": "string", "duplicate_charge_explanation": "string", "duplicate_charge_id": "string", "uncategorized_text": "string", "customer_communication": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "customer_signature": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "shipping_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "receipt": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "duplicate_charge_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "service_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "uncategorized_file": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "cancellation_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "refund_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" } }, "evidence_details": { "due_by": "2026-06-15T14:30:00Z", "has_evidence": false, "past_due": false, "submission_count": 3 }, "balance_transactions": [ { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "fee": 2500, "net": 2500, "status": "available", "type": "string", "reporting_category": "example_value", "category": "example_value", "created_at": "2026-06-15T14:30:00Z" } ], "payment_method_details": { "type": "string", "card": { "brand": "visa", "network_reason_code": "example_value" } }, "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } }, "DisputeBody_for_UpdateDispute": { "description": "An envelope wrapping a single dispute object.", "type": "object", "required": [ "dispute" ], "properties": { "dispute": { "description": "The dispute.", "$ref": "#/components/schemas/UpdateDispute" } }, "example": { "dispute": { "evidence": { "access_activity_log": "example_value", "billing_address": "123 Main St", "cancellation_policy": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "cancellation_policy_disclosure": "example_value", "cancellation_rebuttal": "example_value", "customer_communication": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer_email_address": "john.doe@example.com", "customer_name": "Example", "customer_purchase_ip": "example_value", "customer_signature": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "duplicate_charge_documentation": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "duplicate_charge_explanation": "example_value", "duplicate_charge_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_description": "Premium SPF 50 mineral sunscreen", "receipt": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "refund_policy": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "refund_policy_disclosure": "example_value", "refund_refusal_explanation": "example_value", "service_date": "example_value", "service_documentation": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_address": "123 Main St", "shipping_carrier": "example_value", "shipping_date": "example_value", "shipping_documentation": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_tracking_number": "example_value", "uncategorized_file": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "uncategorized_text": "example_value" }, "submit": false } } }, "UpdateDispute": { "description": "Parameters for updating a dispute's evidence and optionally submitting it to the card network.", "type": "object", "properties": { "evidence": { "description": "Evidence to attach to the dispute. Fields you omit are left unchanged; send a file field as `\"\"` to clear it.", "anyOf": [ { "$ref": "#/components/schemas/UpdateDisputeEvidence" }, { "type": "null" } ] }, "submit": { "description": "Whether to submit the dispute evidence to the card network. When `true`, the saved evidence is finalized and submitted; you cannot edit evidence after submission. Defaults to `false`, which saves evidence as a draft without submitting it.", "type": [ "boolean", "null" ], "example": false } }, "example": { "evidence": { "access_activity_log": "example_value", "billing_address": "123 Main St", "cancellation_policy": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "cancellation_policy_disclosure": "example_value", "cancellation_rebuttal": "example_value", "customer_communication": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer_email_address": "john.doe@example.com", "customer_name": "Example", "customer_purchase_ip": "example_value", "customer_signature": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "duplicate_charge_documentation": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "duplicate_charge_explanation": "example_value", "duplicate_charge_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_description": "Premium SPF 50 mineral sunscreen", "receipt": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "refund_policy": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "refund_policy_disclosure": "example_value", "refund_refusal_explanation": "example_value", "service_date": "example_value", "service_documentation": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_address": "123 Main St", "shipping_carrier": "example_value", "shipping_date": "example_value", "shipping_documentation": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_tracking_number": "example_value", "uncategorized_file": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "uncategorized_text": "example_value" }, "submit": false } }, "UpdateDisputeEvidence": { "description": "Dispute evidence fields to set on an update request. File fields take a Flex file ID (`ffile_xxx`). Send `\"\"` (empty string) for a file field to clear it. Omit the field to leave it unchanged.", "type": "object", "properties": { "access_activity_log": { "description": "A description of the activity on the customer's account or the order, showing that they accessed or used the product or service. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "example_value" }, "billing_address": { "description": "The billing address provided by the customer. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "123 Main St" }, "cancellation_policy": { "description": "Flex file ID. Send `\"\"` to clear; omit to leave unchanged.", "type": [ "string", "null" ], "example": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "cancellation_policy_disclosure": { "description": "Your cancellation policy as shown to the customer. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "example_value" }, "cancellation_rebuttal": { "description": "An explanation of how the customer was shown that the subscription or service was not canceled. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "example_value" }, "customer_communication": { "description": "Flex file ID. Send `\"\"` to clear; omit to leave unchanged.", "type": [ "string", "null" ], "example": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "customer_email_address": { "description": "The email address of the customer. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "john.doe@example.com" }, "customer_name": { "description": "The name of the customer. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "Example" }, "customer_purchase_ip": { "description": "The IP address from which the customer made the purchase. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "example_value" }, "customer_signature": { "description": "Flex file ID. Send `\"\"` to clear; omit to leave unchanged.", "type": [ "string", "null" ], "example": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "duplicate_charge_documentation": { "description": "Flex file ID. Send `\"\"` to clear; omit to leave unchanged.", "type": [ "string", "null" ], "example": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "duplicate_charge_explanation": { "description": "An explanation of the difference between the disputed payment and the charge the customer believes is a duplicate. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "example_value" }, "duplicate_charge_id": { "description": "The ID of the charge the customer claims is a duplicate of the disputed charge. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "product_description": { "description": "A description of the product or service purchased and an explanation of why the customer's claim is unwarranted. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" }, "receipt": { "description": "Flex file ID. Send `\"\"` to clear; omit to leave unchanged.", "type": [ "string", "null" ], "example": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "refund_policy": { "description": "Flex file ID. Send `\"\"` to clear; omit to leave unchanged.", "type": [ "string", "null" ], "example": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "refund_policy_disclosure": { "description": "Your refund policy as shown to the customer. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "example_value" }, "refund_refusal_explanation": { "description": "An explanation of why the customer is not entitled to a refund. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "example_value" }, "service_date": { "description": "The date on which the service was provided to the customer. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "example_value" }, "service_documentation": { "description": "Flex file ID. Send `\"\"` to clear; omit to leave unchanged.", "type": [ "string", "null" ], "example": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "shipping_address": { "description": "The address to which a physical product was shipped. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "123 Main St" }, "shipping_carrier": { "description": "The delivery service that shipped a physical product (e.g., `usps`, `fedex`). Omit to leave unchanged.", "type": [ "string", "null" ], "example": "example_value" }, "shipping_date": { "description": "The date on which a physical product was shipped to the customer. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "example_value" }, "shipping_documentation": { "description": "Flex file ID. Send `\"\"` to clear; omit to leave unchanged.", "type": [ "string", "null" ], "example": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "shipping_tracking_number": { "description": "The tracking number for a physical product shipped to the customer. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "example_value" }, "uncategorized_file": { "description": "Flex file ID. Send `\"\"` to clear; omit to leave unchanged.", "type": [ "string", "null" ], "example": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "uncategorized_text": { "description": "Any additional evidence as free-form text. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "example_value" } }, "example": { "access_activity_log": "example_value", "billing_address": "123 Main St", "cancellation_policy": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "cancellation_policy_disclosure": "example_value", "cancellation_rebuttal": "example_value", "customer_communication": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer_email_address": "john.doe@example.com", "customer_name": "Example", "customer_purchase_ip": "example_value", "customer_signature": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "duplicate_charge_documentation": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "duplicate_charge_explanation": "example_value", "duplicate_charge_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_description": "Premium SPF 50 mineral sunscreen", "receipt": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "refund_policy": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "refund_policy_disclosure": "example_value", "refund_refusal_explanation": "example_value", "service_date": "example_value", "service_documentation": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_address": "123 Main St", "shipping_carrier": "example_value", "shipping_date": "example_value", "shipping_documentation": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_tracking_number": "example_value", "uncategorized_file": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "uncategorized_text": "example_value" } }, "EventBody_for_RetryEventRequest": { "description": "An envelope wrapping a single event object.", "type": "object", "required": [ "event" ], "properties": { "event": { "description": "The Event, or the request describing how to retry it.", "$ref": "#/components/schemas/RetryEventRequest" } }, "example": { "event": { "webhook_id": "fwh_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } }, "RetryEventRequest": { "description": "Parameters for retrying an event against a specific webhook endpoint.", "type": "object", "required": [ "webhook_id" ], "properties": { "webhook_id": { "description": "ID of the webhook endpoint to redeliver this event to, prefixed with `fwh_`. Must be one of your webhook endpoints.", "type": "string", "example": "fwh_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "example": { "webhook_id": "fwh_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "EventBody_for_Event": { "description": "An envelope wrapping a single event object.", "type": "object", "required": [ "event" ], "properties": { "event": { "description": "The Event, or the request describing how to retry it.", "$ref": "#/components/schemas/Event" } }, "example": { "event": { "event_id": "fevt_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "event_type": "account.updated", "object": { "external_partner": { "origin": "shopify", "domain": "example_value", "flex_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "access_token": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z" }, "customer": { "customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D", "owner_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false }, "checkout_session": { "allow_promotion_codes": false, "amount_total": 2500, "amount_subtotal": 2500, "amount_received": 2500, "amount_refunded": 2500, "amount_disputed": 2500, "cancel_url": "https://example.com", "captures": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "disputes": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "capture_method": "automatic", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "example_value", "created_at": 2500, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "expires_at": 2500, "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "hsa_fsa_eligible": false, "letter_of_medical_necessity_required": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "mode": "payment", "origin": "shopify", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intents": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "redirect_url": "https://example.com", "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "shipping_address_collection": false, "shipping_details": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "open", "success_url": "https://example.com", "fees": [ { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } }, "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription_data": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "test_mode": false, "total_details": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "visit_type": "cbtSleep", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "next_action": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "selling_plans": [ { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } ], "shopify_payment_details": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } }, "renewal_as_of": 1781533800, "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "platform_fees": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } }, "subscription": { "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "quantity": 2500, "created_at": "2026-06-15T14:30:00Z", "updated_at": "2026-06-15T14:30:00Z", "test_mode": false } ], "latest_invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "incomplete", "cancel_at_period_end": false, "current_period_end": "string", "current_period_start": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false, "client_secret": { "setup_secret": "string", "payment_secret": "string" }, "proration_behavior": "always_invoice", "trial_start": "string", "trial_end": "string", "cancel_at": "2026-06-15T14:30:00Z", "canceled_at": "2026-06-15T14:30:00Z", "default_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "discounts": [ { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } ], "pause": { "paused_at": "2026-06-15T14:30:00Z", "resume_at": "2026-06-15T14:30:00Z" } }, "payment_intent": { "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "amount_capturable": 2500, "amount_received": 2500, "application_fee_amount": 0, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "transfer_data": { "amount": 2500, "destination": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "status": "canceled", "latest_charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "capture_method": "automatic", "client_secret": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "transfer_group": "example_value", "payment_card_type": "primary", "letter_fee_amount": 0, "transaction_fee": 0, "last_payment_error": { "type": "string", "code": "string", "decline_code": "string", "message": "string", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "setup_intent": { "setup_intent_id": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_secret": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "status": "requires_payment_method", "usage": "off_session", "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "invoice": { "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "total": 2500, "amount_due": 2500, "amount_paid": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "period_end": "string", "period_start": "string", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "paid_at": "string", "status": "draft", "collection_method": "charge_automatically", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "backup_charge_status": "pending" }, "dispute": { "dispute_id": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "currency": "usd", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "status": "lost", "reason": "bank_cannot_process", "is_charge_refundable": false, "evidence": { "access_activity_log": "string", "customer_name": "string", "customer_email_address": "string", "customer_purchase_ip": "string", "billing_address": "string", "shipping_address": "string", "shipping_tracking_number": "string", "shipping_carrier": "string", "shipping_date": "string", "service_date": "string", "product_description": "string", "refund_policy_disclosure": "string", "refund_refusal_explanation": "string", "cancellation_policy_disclosure": "string", "cancellation_rebuttal": "string", "duplicate_charge_explanation": "string", "duplicate_charge_id": "string", "uncategorized_text": "string", "customer_communication": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "customer_signature": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "shipping_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "receipt": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "duplicate_charge_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "service_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "uncategorized_file": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "cancellation_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "refund_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" } }, "evidence_details": { "due_by": "2026-06-15T14:30:00Z", "has_evidence": false, "past_due": false, "submission_count": 3 }, "balance_transactions": [ { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "fee": 2500, "net": 2500, "status": "available", "type": "string", "reporting_category": "example_value", "category": "example_value", "created_at": "2026-06-15T14:30:00Z" } ], "payment_method_details": { "type": "string", "card": { "brand": "visa", "network_reason_code": "example_value" } }, "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "early_fraud_warning": { "early_fraud_warning_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "actionable": false, "fraud_type": "card_never_received", "partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z" }, "review": { "review_id": "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reason": "rule", "opened_reason": "rule", "closed_reason": "approved", "open": false, "billing_zip": "string", "ip_address": "string", "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z" }, "refund": { "refund_id": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "created_at": "2026-06-15T14:30:00Z", "reason": "duplicate", "status": "pending", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available", "items": [ { "amount_refunded": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available" } ], "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "charge": { "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "amount_captured": 2500, "amount_refunded": 2500, "application_fee_amount": 0, "captured": false, "created_at": "2026-06-15T14:30:00Z", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_message": "Premium SPF 50 mineral sunscreen", "disputed": false, "paid": false, "refunded": false, "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "succeeded", "test_mode": false, "transfer_group": "example_value", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "three_d_secure": { "authentication_flow": "string", "result": "string", "result_reason": "string", "version": "string" }, "decline_details": { "failure_code": "string", "decline_code": "string", "failure_message": "string", "outcome_type": "string", "network_status": "string", "seller_message": "string", "reason": "string", "risk_level": "string" }, "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "export": { "export_id": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "type": "product", "status": "created", "created_at": "2026-06-15T14:30:00Z", "started_at": "2026-06-15T14:30:00Z", "completed_at": "2026-06-15T14:30:00Z", "metadata": { "order_id": "8842", "channel": "shopify" }, "filters": { "payment": { "limit": 0, "status": "canceled", "starting_after": "string", "ending_before": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "limit": 0, "offset": 0, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string", "start_date": "string", "end_date": "string" }, "subscription": { "limit": 0, "offset": 0, "start_date": "string", "end_date": "string" }, "customer": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "product": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "charge_reconciliation": { "start_date": "string", "end_date": "string" }, "payout": { "start_date": "string", "end_date": "string" }, "dispute": { "start_date": "string", "end_date": "string" }, "line_item": { "start_date": "string", "end_date": "string" }, "line_item_revenue": { "start_date": "string", "end_date": "string" }, "balance_activity": { "start_date": "string", "end_date": "string" } }, "test_mode": false }, "payment_method": { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "billing_details": { "address": { "city": "San Francisco", "country": "US", "line1": "123 Main St", "line2": "Suite 100", "postal_code": "94107", "state": "CA" }, "email": "john.doe@example.com", "name": "Example", "phone": "+14155550142" }, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "card": { "brand": "american_express", "country": "US", "exp_month": 12, "exp_year": 2027, "fingerprint": "abc123", "funding": "credit", "last4": "4242" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "off_session": true }, "product": { "product_id": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "document_description": "string", "receipt_description": "string", "created_at": "2026-06-15T14:30:00Z", "visit_type": "cbtSleep", "active": false, "upc_code": "string", "gtin": "string", "reference_gtin": "string", "hsa_fsa_eligibility": "not_eligible", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "balance_transaction": { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "available_on": "string", "created_at": "2026-06-15T14:30:00Z", "exchange_rate": 1.0, "fee": 2500, "net": 2500, "reporting_category": "example_value", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "available", "source_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "string", "flex_payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "mid": "example_value", "currency": "usd", "metadata": { "order_id": "8842", "channel": "shopify" }, "transaction_fee_amount": 0, "interchange_fee_amount": 0, "lmn_fee_amount": 0, "dispute_fee_amount": 0, "card_type": "string", "card_network": "string" } }, "test_mode": false, "created_at": "2026-06-15T14:30:00Z" } } }, "Event": { "description": "An Event object represents a notable change to an object in your Flex account — for example a checkout session completing or a refund being created. Events are created automatically when their underlying object changes and are delivered to your configured webhook endpoints. Use them to keep your systems in sync with Flex.", "type": "object", "required": [ "created_at", "event_id", "event_type", "object", "test_mode" ], "properties": { "event_id": { "description": "Unique identifier for the event, prefixed with `fevt_`.", "type": "string", "example": "fevt_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "event_type": { "description": "The kind of change this event describes, such as `checkout.session.completed` or `refund.updated`. The value also determines the type of object found in `object`.", "$ref": "#/components/schemas/EventType" }, "object": { "description": "The API object affected by this event (for example the CheckoutSession, Refund, or Customer). Its shape depends on `event_type`.", "$ref": "#/components/schemas/EventObject" }, "test_mode": { "description": "Whether the event was generated in test mode. `true` for events from test-mode objects, `false` for live-mode objects.", "type": "boolean", "example": false }, "created_at": { "description": "Time at which the event was created, as an RFC 3339 / ISO 8601 timestamp (e.g., `2026-06-15T17:04:05Z`).", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" } }, "example": { "event_id": "fevt_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "event_type": "account.updated", "object": { "external_partner": { "origin": "shopify", "domain": "example_value", "flex_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "access_token": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z" }, "customer": { "customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D", "owner_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false }, "checkout_session": { "allow_promotion_codes": false, "amount_total": 2500, "amount_subtotal": 2500, "amount_received": 2500, "amount_refunded": 2500, "amount_disputed": 2500, "cancel_url": "https://example.com", "captures": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "disputes": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "capture_method": "automatic", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "example_value", "created_at": 2500, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "expires_at": 2500, "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "hsa_fsa_eligible": false, "letter_of_medical_necessity_required": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "mode": "payment", "origin": "shopify", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intents": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "redirect_url": "https://example.com", "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "shipping_address_collection": false, "shipping_details": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "open", "success_url": "https://example.com", "fees": [ { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } }, "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription_data": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "test_mode": false, "total_details": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "visit_type": "cbtSleep", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "next_action": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "selling_plans": [ { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } ], "shopify_payment_details": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } }, "renewal_as_of": 1781533800, "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "platform_fees": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } }, "subscription": { "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "quantity": 2500, "created_at": "2026-06-15T14:30:00Z", "updated_at": "2026-06-15T14:30:00Z", "test_mode": false } ], "latest_invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "incomplete", "cancel_at_period_end": false, "current_period_end": "string", "current_period_start": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false, "client_secret": { "setup_secret": "string", "payment_secret": "string" }, "proration_behavior": "always_invoice", "trial_start": "string", "trial_end": "string", "cancel_at": "2026-06-15T14:30:00Z", "canceled_at": "2026-06-15T14:30:00Z", "default_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "discounts": [ { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } ], "pause": { "paused_at": "2026-06-15T14:30:00Z", "resume_at": "2026-06-15T14:30:00Z" } }, "payment_intent": { "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "amount_capturable": 2500, "amount_received": 2500, "application_fee_amount": 0, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "transfer_data": { "amount": 2500, "destination": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "status": "canceled", "latest_charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "capture_method": "automatic", "client_secret": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "transfer_group": "example_value", "payment_card_type": "primary", "letter_fee_amount": 0, "transaction_fee": 0, "last_payment_error": { "type": "string", "code": "string", "decline_code": "string", "message": "string", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "setup_intent": { "setup_intent_id": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_secret": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "status": "requires_payment_method", "usage": "off_session", "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "invoice": { "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "total": 2500, "amount_due": 2500, "amount_paid": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "period_end": "string", "period_start": "string", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "paid_at": "string", "status": "draft", "collection_method": "charge_automatically", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "backup_charge_status": "pending" }, "dispute": { "dispute_id": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "currency": "usd", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "status": "lost", "reason": "bank_cannot_process", "is_charge_refundable": false, "evidence": { "access_activity_log": "string", "customer_name": "string", "customer_email_address": "string", "customer_purchase_ip": "string", "billing_address": "string", "shipping_address": "string", "shipping_tracking_number": "string", "shipping_carrier": "string", "shipping_date": "string", "service_date": "string", "product_description": "string", "refund_policy_disclosure": "string", "refund_refusal_explanation": "string", "cancellation_policy_disclosure": "string", "cancellation_rebuttal": "string", "duplicate_charge_explanation": "string", "duplicate_charge_id": "string", "uncategorized_text": "string", "customer_communication": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "customer_signature": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "shipping_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "receipt": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "duplicate_charge_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "service_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "uncategorized_file": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "cancellation_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "refund_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" } }, "evidence_details": { "due_by": "2026-06-15T14:30:00Z", "has_evidence": false, "past_due": false, "submission_count": 3 }, "balance_transactions": [ { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "fee": 2500, "net": 2500, "status": "available", "type": "string", "reporting_category": "example_value", "category": "example_value", "created_at": "2026-06-15T14:30:00Z" } ], "payment_method_details": { "type": "string", "card": { "brand": "visa", "network_reason_code": "example_value" } }, "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "early_fraud_warning": { "early_fraud_warning_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "actionable": false, "fraud_type": "card_never_received", "partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z" }, "review": { "review_id": "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reason": "rule", "opened_reason": "rule", "closed_reason": "approved", "open": false, "billing_zip": "string", "ip_address": "string", "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z" }, "refund": { "refund_id": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "created_at": "2026-06-15T14:30:00Z", "reason": "duplicate", "status": "pending", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available", "items": [ { "amount_refunded": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available" } ], "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "charge": { "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "amount_captured": 2500, "amount_refunded": 2500, "application_fee_amount": 0, "captured": false, "created_at": "2026-06-15T14:30:00Z", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_message": "Premium SPF 50 mineral sunscreen", "disputed": false, "paid": false, "refunded": false, "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "succeeded", "test_mode": false, "transfer_group": "example_value", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "three_d_secure": { "authentication_flow": "string", "result": "string", "result_reason": "string", "version": "string" }, "decline_details": { "failure_code": "string", "decline_code": "string", "failure_message": "string", "outcome_type": "string", "network_status": "string", "seller_message": "string", "reason": "string", "risk_level": "string" }, "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "export": { "export_id": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "type": "product", "status": "created", "created_at": "2026-06-15T14:30:00Z", "started_at": "2026-06-15T14:30:00Z", "completed_at": "2026-06-15T14:30:00Z", "metadata": { "order_id": "8842", "channel": "shopify" }, "filters": { "payment": { "limit": 0, "status": "canceled", "starting_after": "string", "ending_before": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "limit": 0, "offset": 0, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string", "start_date": "string", "end_date": "string" }, "subscription": { "limit": 0, "offset": 0, "start_date": "string", "end_date": "string" }, "customer": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "product": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "charge_reconciliation": { "start_date": "string", "end_date": "string" }, "payout": { "start_date": "string", "end_date": "string" }, "dispute": { "start_date": "string", "end_date": "string" }, "line_item": { "start_date": "string", "end_date": "string" }, "line_item_revenue": { "start_date": "string", "end_date": "string" }, "balance_activity": { "start_date": "string", "end_date": "string" } }, "test_mode": false }, "payment_method": { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "billing_details": { "address": { "city": "San Francisco", "country": "US", "line1": "123 Main St", "line2": "Suite 100", "postal_code": "94107", "state": "CA" }, "email": "john.doe@example.com", "name": "Example", "phone": "+14155550142" }, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "card": { "brand": "american_express", "country": "US", "exp_month": 12, "exp_year": 2027, "fingerprint": "abc123", "funding": "credit", "last4": "4242" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "off_session": true }, "product": { "product_id": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "document_description": "string", "receipt_description": "string", "created_at": "2026-06-15T14:30:00Z", "visit_type": "cbtSleep", "active": false, "upc_code": "string", "gtin": "string", "reference_gtin": "string", "hsa_fsa_eligibility": "not_eligible", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "balance_transaction": { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "available_on": "string", "created_at": "2026-06-15T14:30:00Z", "exchange_rate": 1.0, "fee": 2500, "net": 2500, "reporting_category": "example_value", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "available", "source_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "string", "flex_payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "mid": "example_value", "currency": "usd", "metadata": { "order_id": "8842", "channel": "shopify" }, "transaction_fee_amount": 0, "interchange_fee_amount": 0, "lmn_fee_amount": 0, "dispute_fee_amount": 0, "card_type": "string", "card_network": "string" } }, "test_mode": false, "created_at": "2026-06-15T14:30:00Z" } }, "EventType": { "description": "The type of event, identifying which resource changed and how. Values are dot-namespaced by resource and action (for example checkout_session.completed or refund.updated).", "type": "string", "enum": [ "account.updated", "charge.dispute.closed", "charge.dispute.created", "charge.dispute.funds_reinstated", "charge.dispute.funds_withdrawn", "charge.dispute.updated", "charge.failed", "charge.pending", "charge.refund.updated", "charge.refunded", "charge.captured", "charge.expired", "charge.updated", "charge.succeeded", "checkout.session.completed", "checkout.session.async_payment_succeeded", "checkout.session.async_payment_failed", "checkout.session.refunded", "checkout.session.expired", "customer.created", "customer.deleted", "customer.discount.created", "customer.discount.updated", "customer.discount.deleted", "customer.subscription.updated", "customer.subscription.deleted", "customer.subscription.created", "customer.source.deleted", "invoice.created", "invoice.finalized", "invoice.paid", "invoice.updated", "invoice.payment_succeeded", "invoice.payment_failed", "payment_intent.succeeded", "payment_intent.created", "payment_intent.payment_failed", "payment_intent.amount_capturable_updated", "payment_intent.canceled", "payment_intent.processing", "payment_intent.requires_action", "payment_intent.requires_capture", "payment_method.attached", "payment_method.automatically_updated", "payment_method.detached", "payment_method.updated", "product.created", "product.updated", "payout.created", "payout.paid", "payout.failed", "payout.canceled", "payout.updated", "payout.reconciliation_completed", "refund.created", "refund.updated", "refund.failed", "setup_intent.succeeded", "setup_intent.created", "setup_intent.setup_failed", "setup_intent.requires_action", "setup_intent.canceled", "transfer.created", "transfer.failed", "transfer.paid", "transfer.reversed", "transfer.updated", "balance_transaction.created", "radar.early_fraud_warning.created", "radar.early_fraud_warning.updated", "review.opened", "review.closed", "reporting.report_run.succeeded", "reporting.report_run.failed" ], "example": "account.updated" }, "EventObject": { "description": "The resource payload carried by an Event. The variant present corresponds to the event's type — for example a `customer.created` event carries a Customer, and a `payment_intent.succeeded` event carries a PaymentIntent.", "type": "object", "properties": { "external_partner": { "$ref": "#/components/schemas/ExternalPartner", "description": "The external partner account that the event describes." }, "customer": { "$ref": "#/components/schemas/Customer", "description": "The customer that the event describes." }, "checkout_session": { "$ref": "#/components/schemas/CheckoutSession", "description": "The checkout session that the event describes." }, "subscription": { "$ref": "#/components/schemas/Subscription", "description": "The subscription that the event describes." }, "payment_intent": { "$ref": "#/components/schemas/PaymentIntent", "description": "The payment intent that the event describes." }, "setup_intent": { "$ref": "#/components/schemas/SetupIntent", "description": "The setup intent that the event describes." }, "invoice": { "$ref": "#/components/schemas/Invoice", "description": "The invoice that the event describes." }, "dispute": { "$ref": "#/components/schemas/Dispute", "description": "The dispute that the event describes." }, "early_fraud_warning": { "$ref": "#/components/schemas/EarlyFraudWarning", "description": "The early fraud warning that the event describes." }, "review": { "$ref": "#/components/schemas/Review", "description": "The review that the event describes." }, "refund": { "$ref": "#/components/schemas/Refund", "description": "The refund that the event describes." }, "charge": { "$ref": "#/components/schemas/Charge", "description": "The charge that the event describes." }, "export": { "$ref": "#/components/schemas/Export", "description": "The export that the event describes." }, "payment_method": { "$ref": "#/components/schemas/PaymentMethod", "description": "The payment method that the event describes." }, "product": { "$ref": "#/components/schemas/Product", "description": "The product that the event describes." }, "balance_transaction": { "$ref": "#/components/schemas/BalanceTransaction", "description": "The balance transaction that the event describes." } }, "additionalProperties": false, "example": { "external_partner": { "origin": "shopify", "domain": "example_value", "flex_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "access_token": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z" }, "customer": { "customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D", "owner_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false }, "checkout_session": { "allow_promotion_codes": false, "amount_total": 2500, "amount_subtotal": 2500, "amount_received": 2500, "amount_refunded": 2500, "amount_disputed": 2500, "cancel_url": "https://example.com", "captures": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "disputes": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "capture_method": "automatic", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "example_value", "created_at": 2500, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "expires_at": 2500, "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "hsa_fsa_eligible": false, "letter_of_medical_necessity_required": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "mode": "payment", "origin": "shopify", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intents": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "redirect_url": "https://example.com", "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "shipping_address_collection": false, "shipping_details": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "open", "success_url": "https://example.com", "fees": [ { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } }, "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription_data": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "test_mode": false, "total_details": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "visit_type": "cbtSleep", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "next_action": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "selling_plans": [ { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } ], "shopify_payment_details": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } }, "renewal_as_of": 1781533800, "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "platform_fees": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } }, "subscription": { "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "quantity": 2500, "created_at": "2026-06-15T14:30:00Z", "updated_at": "2026-06-15T14:30:00Z", "test_mode": false } ], "latest_invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "incomplete", "cancel_at_period_end": false, "current_period_end": "string", "current_period_start": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false, "client_secret": { "setup_secret": "string", "payment_secret": "string" }, "proration_behavior": "always_invoice", "trial_start": "string", "trial_end": "string", "cancel_at": "2026-06-15T14:30:00Z", "canceled_at": "2026-06-15T14:30:00Z", "default_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "discounts": [ { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } ], "pause": { "paused_at": "2026-06-15T14:30:00Z", "resume_at": "2026-06-15T14:30:00Z" } }, "payment_intent": { "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "amount_capturable": 2500, "amount_received": 2500, "application_fee_amount": 0, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "transfer_data": { "amount": 2500, "destination": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "status": "canceled", "latest_charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "capture_method": "automatic", "client_secret": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "transfer_group": "example_value", "payment_card_type": "primary", "letter_fee_amount": 0, "transaction_fee": 0, "last_payment_error": { "type": "string", "code": "string", "decline_code": "string", "message": "string", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "setup_intent": { "setup_intent_id": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_secret": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "status": "requires_payment_method", "usage": "off_session", "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "invoice": { "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "total": 2500, "amount_due": 2500, "amount_paid": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "period_end": "string", "period_start": "string", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "paid_at": "string", "status": "draft", "collection_method": "charge_automatically", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "backup_charge_status": "pending" }, "dispute": { "dispute_id": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "currency": "usd", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "status": "lost", "reason": "bank_cannot_process", "is_charge_refundable": false, "evidence": { "access_activity_log": "string", "customer_name": "string", "customer_email_address": "string", "customer_purchase_ip": "string", "billing_address": "string", "shipping_address": "string", "shipping_tracking_number": "string", "shipping_carrier": "string", "shipping_date": "string", "service_date": "string", "product_description": "string", "refund_policy_disclosure": "string", "refund_refusal_explanation": "string", "cancellation_policy_disclosure": "string", "cancellation_rebuttal": "string", "duplicate_charge_explanation": "string", "duplicate_charge_id": "string", "uncategorized_text": "string", "customer_communication": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "customer_signature": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "shipping_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "receipt": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "duplicate_charge_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "service_documentation": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "uncategorized_file": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "cancellation_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" }, "refund_policy": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "filename": "string", "stripe_file_id": "string" } }, "evidence_details": { "due_by": "2026-06-15T14:30:00Z", "has_evidence": false, "past_due": false, "submission_count": 3 }, "balance_transactions": [ { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "fee": 2500, "net": 2500, "status": "available", "type": "string", "reporting_category": "example_value", "category": "example_value", "created_at": "2026-06-15T14:30:00Z" } ], "payment_method_details": { "type": "string", "card": { "brand": "visa", "network_reason_code": "example_value" } }, "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "early_fraud_warning": { "early_fraud_warning_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "actionable": false, "fraud_type": "card_never_received", "partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z" }, "review": { "review_id": "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reason": "rule", "opened_reason": "rule", "closed_reason": "approved", "open": false, "billing_zip": "string", "ip_address": "string", "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z" }, "refund": { "refund_id": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "created_at": "2026-06-15T14:30:00Z", "reason": "duplicate", "status": "pending", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available", "items": [ { "amount_refunded": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available" } ], "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "charge": { "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "amount_captured": 2500, "amount_refunded": 2500, "application_fee_amount": 0, "captured": false, "created_at": "2026-06-15T14:30:00Z", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_message": "Premium SPF 50 mineral sunscreen", "disputed": false, "paid": false, "refunded": false, "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "succeeded", "test_mode": false, "transfer_group": "example_value", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "three_d_secure": { "authentication_flow": "string", "result": "string", "result_reason": "string", "version": "string" }, "decline_details": { "failure_code": "string", "decline_code": "string", "failure_message": "string", "outcome_type": "string", "network_status": "string", "seller_message": "string", "reason": "string", "risk_level": "string" }, "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "export": { "export_id": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "type": "product", "status": "created", "created_at": "2026-06-15T14:30:00Z", "started_at": "2026-06-15T14:30:00Z", "completed_at": "2026-06-15T14:30:00Z", "metadata": { "order_id": "8842", "channel": "shopify" }, "filters": { "payment": { "limit": 0, "status": "canceled", "starting_after": "string", "ending_before": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "limit": 0, "offset": 0, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string", "start_date": "string", "end_date": "string" }, "subscription": { "limit": 0, "offset": 0, "start_date": "string", "end_date": "string" }, "customer": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "product": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "charge_reconciliation": { "start_date": "string", "end_date": "string" }, "payout": { "start_date": "string", "end_date": "string" }, "dispute": { "start_date": "string", "end_date": "string" }, "line_item": { "start_date": "string", "end_date": "string" }, "line_item_revenue": { "start_date": "string", "end_date": "string" }, "balance_activity": { "start_date": "string", "end_date": "string" } }, "test_mode": false }, "payment_method": { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "billing_details": { "address": { "city": "San Francisco", "country": "US", "line1": "123 Main St", "line2": "Suite 100", "postal_code": "94107", "state": "CA" }, "email": "john.doe@example.com", "name": "Example", "phone": "+14155550142" }, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "card": { "brand": "american_express", "country": "US", "exp_month": 12, "exp_year": 2027, "fingerprint": "abc123", "funding": "credit", "last4": "4242" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "off_session": true }, "product": { "product_id": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "document_description": "string", "receipt_description": "string", "created_at": "2026-06-15T14:30:00Z", "visit_type": "cbtSleep", "active": false, "upc_code": "string", "gtin": "string", "reference_gtin": "string", "hsa_fsa_eligibility": "not_eligible", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "balance_transaction": { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "available_on": "string", "created_at": "2026-06-15T14:30:00Z", "exchange_rate": 1.0, "fee": 2500, "net": 2500, "reporting_category": "example_value", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "available", "source_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "string", "flex_payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "mid": "example_value", "currency": "usd", "metadata": { "order_id": "8842", "channel": "shopify" }, "transaction_fee_amount": 0, "interchange_fee_amount": 0, "lmn_fee_amount": 0, "dispute_fee_amount": 0, "card_type": "string", "card_network": "string" } } }, "ExternalPartner": { "description": "A Mapping between an internal Flex partner and an external domain that merchants may be using on some other platform.", "type": "object", "required": [ "created_at", "domain", "flex_partner_id", "origin" ], "properties": { "origin": { "description": "The source of the external partner.", "$ref": "#/components/schemas/ExternalOrigin" }, "domain": { "description": "The ID/URL/handle for the partner on the external platform", "type": "string", "example": "example_value" }, "flex_partner_id": { "description": "The flex partner identifier", "type": "string", "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "access_token": { "description": "access token", "type": [ "string", "null" ], "example": "example_value" }, "metadata": { "description": "metadata", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": { "order_id": "8842", "channel": "shopify" } }, "created_at": { "description": "The date the partner was created.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" } }, "example": { "origin": "shopify", "domain": "example_value", "flex_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "access_token": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z" } }, "ExternalOrigin": { "description": "External e-commerce platforms that may be the source for partners, products, and prices created internally in Flex", "type": "string", "enum": [ "shopify", "shopline" ], "example": "shopify" }, "Customer": { "description": "A Customer object represents a customer of your business. Use it to track payments, store reusable payment methods, and reference the customer on checkout sessions, invoices, and subscriptions.", "type": "object", "required": [ "created_at", "customer_id", "email", "first_name", "last_name", "test_mode" ], "properties": { "customer_id": { "description": "The unique identifier for the customer.", "type": "string", "example": "fcus_01HACM7FZ1084XB1GB6053VM0D" }, "owner_partner_id": { "description": "The partner that owns this customer. When a customer is shared with you by another partner in your organization, this is that sibling partner; otherwise it is your own partner id.", "type": [ "string", "null" ], "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "first_name": { "description": "The customer's first name.", "type": "string", "example": "John" }, "last_name": { "description": "The customer's last name.", "type": "string", "example": "Doe" }, "email": { "description": "The customer's email address.", "type": "string", "example": "joh.doe@example.com" }, "phone": { "description": "The customer's phone number.", "type": [ "string", "null" ], "format": "phone", "example": "+15555555555" }, "employer": { "description": "The customer's employer.", "type": [ "string", "null" ], "example": "Flex" }, "shipping": { "description": "The customer's shipping address.", "anyOf": [ { "$ref": "#/components/schemas/ShippingAddress" }, { "type": "null" } ] }, "metadata": { "description": "Metadata associated with the customer.", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": { "order_id": "8842", "channel": "shopify" } }, "created_at": { "description": "The time the customer was created.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "test_mode": { "description": "Whether the customer was created in test mode.", "type": "boolean", "example": false } }, "example": { "customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D", "owner_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false } }, "ShippingAddress": { "description": "A ShippingAddress represents the postal address a physical order is delivered to. It is referenced by checkout sessions and customers.", "type": "object", "required": [ "shipping_address_id" ], "properties": { "shipping_address_id": { "description": "Unique identifier for the shipping address.", "type": "string", "example": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "line1": { "description": "The first line of the street address (e.g., street number and name).", "type": [ "string", "null" ], "example": "123 Main St" }, "line2": { "description": "The second line of the street address (e.g., apartment, suite, or unit).", "type": [ "string", "null" ], "example": "Suite 100" }, "city": { "description": "City, district, suburb, town, or village.", "type": [ "string", "null" ], "example": "San Francisco" }, "state": { "description": "State, county, province, or region.", "type": [ "string", "null" ], "example": "CA" }, "postal_code": { "description": "ZIP or postal code.", "type": [ "string", "null" ], "example": "94107" }, "country": { "description": "Two-letter country code (ISO 3166-1 alpha-2, e.g., `US`).", "type": [ "string", "null" ], "example": "US" } }, "example": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" } }, "CheckoutSession": { "description": "A Checkout Session represents a customer's session as they pay for one-time purchases or subscriptions through Flex's hosted checkout page. Create one to obtain a hosted `redirect_url`, then capture, refund, or reconcile the resulting payments. For HSA/FSA purchases the session also drives eligibility classification and, when required, collection of a Letter of Medical Necessity (LOMN).", "type": "object", "required": [ "allow_promotion_codes", "amount_subtotal", "amount_total", "capture_method", "captures", "checkout_session_id", "created_at", "expires_at", "hsa_fsa_eligible", "letter_of_medical_necessity_required", "mode", "redirect_url", "refunds", "shipping_address_collection", "status", "success_url", "test_mode", "total_details" ], "properties": { "allow_promotion_codes": { "description": "Whether promotion codes can be applied to the checkout session.", "type": "boolean", "example": false }, "amount_total": { "description": "The total amount of the checkout session.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_subtotal": { "description": "The subtotal amount of the checkout session.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_received": { "description": "The amount actually received from payment intents.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_refunded": { "description": "The total amount refunded for this checkout session.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_disputed": { "description": "The total amount currently in dispute for this checkout session. Includes all dispute statuses except Won and Prevented.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "cancel_url": { "description": "If set, Checkout displays a back button and customers will be directed to this URL if they decide to cancel payment and return to your website.", "type": [ "string", "null" ], "example": "https://example.com" }, "captures": { "description": "A list of captures associated with the checkout session.", "type": "array", "items": { "$ref": "#/components/schemas/Expandable_for_V1Capture" } }, "disputes": { "description": "Disputes associated with this checkout session's payment intents.", "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Expandable_for_Dispute" } }, "capture_method": { "description": "Controls when funds are captured from the customer's account. One of `automatic` or `automatic_async` (capture immediately when the customer pays), or `manual` (authorize the payment and require a later capture via the capture endpoint).", "$ref": "#/components/schemas/PaymentIntentCaptureMethod" }, "checkout_session_id": { "description": "The ID of the Checkout Session.", "type": "string", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "client_reference_id": { "description": "A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the session with your internal systems.", "type": [ "string", "null" ], "example": "example_value" }, "created_at": { "description": "Time at which the Checkout Session was created, as a Unix timestamp in seconds.", "type": "integer", "format": "int64", "example": 2500, "minimum": -9007199254740991.0, "maximum": 9007199254740991.0 }, "customer": { "description": "The ID of the customer for this Session. This object is expandable if expand_customer is set.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_Customer" }, { "type": "null" } ] }, "defaults": { "description": "The customer values to prefill the customer details in the checkout page.", "anyOf": [ { "$ref": "#/components/schemas/CustomerDefaults" }, { "type": "null" } ] }, "expires_at": { "description": "The time at which the Checkout Session will expire.", "type": "integer", "format": "int64", "example": 2500, "minimum": -9007199254740991.0, "maximum": 9007199254740991.0 }, "invoice": { "description": "The ID of the invoice this Checkout Session is for, if any.", "type": [ "string", "null" ], "example": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "hsa_fsa_eligible": { "description": "Whether the Checkout Session is HSA/FSA eligible.", "type": "boolean", "example": false }, "letter_of_medical_necessity_required": { "description": "Whether a letter of medical necessity is required for this Checkout Session.", "type": "boolean", "example": false }, "metadata": { "description": "Metadata to attach to the Checkout Session.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "mode": { "description": "The mode of the Checkout Session.", "$ref": "#/components/schemas/Mode" }, "origin": { "description": "Where the Checkout Session was generated. `null` for sessions created directly via the API.", "anyOf": [ { "$ref": "#/components/schemas/CheckoutSessionOrigin" }, { "type": "null" } ] }, "payment_intent": { "description": "The payment intent that belongs to this Checkout Session. This object is expandable if expand_payment_intent is set.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_PaymentIntent" }, { "type": "null" } ] }, "payment_intents": { "description": "All payment intents that belong to this Checkout Session. Each is expandable if expand_payment_intent is set.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Expandable_for_PaymentIntent" } }, "redirect_url": { "description": "The URL to redirect to access the checkout session.", "type": "string", "format": "uri", "example": "https://example.com" }, "refunds": { "description": "The refunds associated with this Checkout Session.", "type": "array", "items": { "$ref": "#/components/schemas/Expandable_for_Refund" } }, "setup_intent": { "description": "The ID of the SetupIntent for this Checkout Session, if any.", "type": [ "string", "null" ], "example": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "shipping_options": { "description": "The shipping rate options applied to this Session.", "anyOf": [ { "$ref": "#/components/schemas/ShippingRateOptions" }, { "type": "null" } ] }, "shipping_address_collection": { "description": "When set, present options for shipping address collection from a customer.", "type": "boolean", "example": false }, "shipping_details": { "description": "Shipping information for this Checkout Session.", "anyOf": [ { "$ref": "#/components/schemas/ShippingAddress" }, { "type": "null" } ] }, "split_cart": { "description": "If this checkout session contains both items that are eligible for HSA/FSA and items that are not, This will be the ID of the split cart object. This object is expandable if expand_split_cart is set.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_SplitCart" }, { "type": "null" } ] }, "status": { "description": "The status of the checkout session.", "$ref": "#/components/schemas/Status" }, "success_url": { "description": "The URL the customer will be directed to after the payment or subscription creation is successful.", "type": "string", "example": "https://example.com" }, "fees": { "description": "The fees associated with this Checkout Session.", "default": [], "type": "array", "items": { "$ref": "#/components/schemas/V1Fee" } }, "custom_text": { "description": "Custom text displayed to customers during checkout", "anyOf": [ { "$ref": "#/components/schemas/CustomText" }, { "type": "null" } ] }, "subscription": { "description": "The ID of the subscription this Checkout Session is for. This object is expandable if expand_subscription is set.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_Subscription" }, { "type": "null" } ] }, "subscription_data": { "description": "The data that will be used to create a subscription. Populated by default on single-session endpoints (create / retrieve / update) when a subscription_data row exists — no `expand` required. List endpoints omit this field to avoid an extra per-row query.", "anyOf": [ { "$ref": "#/components/schemas/V1SubscriptionData" }, { "type": "null" } ] }, "tax_rate": { "description": "The tax rate for the checkout session.", "anyOf": [ { "$ref": "#/components/schemas/TaxRate" }, { "type": "null" } ] }, "tax_calculation_mode": { "description": "If Flex is calculating the tax, this specifies whether it should be calculated inclusive or exclusive. 'None' means that Flex will not calculate the tax, and the merchant must pass it in as a TaxRate if they want it included.", "anyOf": [ { "$ref": "#/components/schemas/TaxCalculationMode" }, { "type": "null" } ] }, "test_mode": { "description": "Whether the Checkout Session is in test mode.", "type": "boolean", "example": false }, "total_details": { "description": "Tax and discount details for the computed total amount.", "$ref": "#/components/schemas/TotalDetails" }, "visit_type": { "description": "The type of visit this Checkout Session is for.", "anyOf": [ { "$ref": "#/components/schemas/VisitTypeName" }, { "type": "null" } ] }, "setup_future_use": { "description": "How this checkout session enables the payment methods to be used in the future", "default": "on_session", "$ref": "#/components/schemas/FutureUse" }, "payment_method_options": { "description": "Payment method-specific options for this checkout session.", "anyOf": [ { "$ref": "#/components/schemas/PaymentMethodOptions" }, { "type": "null" } ] }, "next_action": { "description": "If present, indicates an action the merchant must take to complete the checkout. Currently used when a Letter of Medical Necessity is required for an off-session payment.", "anyOf": [ { "$ref": "#/components/schemas/NextAction" }, { "type": "null" } ] }, "selling_plans": { "description": "The Shopify selling plan(s) the originating order was placed under. A renewal order carries one, a first checkout can carry several. Omitted when there are none.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/SellingPlan" } }, "shopify_payment_details": { "description": "How the originating Shopify order was paid, as Shopify reported it. Display only. Omitted when there is no Shopify order or it had no successful payment.", "anyOf": [ { "$ref": "#/components/schemas/ShopifyPaymentDetails" }, { "type": "null" } ] }, "renewal_as_of": { "description": "Present only on an LMN renewal session: the instant its coverage checks evaluate against instead of now — the coverage being renewed ends one second before it.", "type": [ "integer", "null" ], "format": "int64", "maximum": 253402300799.0, "minimum": -377705116800.0, "example": 1781533800 }, "partner": { "description": "Your account. Returned as its ID by default; expandable to the full `partner` object when `partner` is expanded.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_PartnerMetadata" }, { "type": "null" } ] }, "platform_fees": { "description": "Platform fees charged on this checkout. Present only for checkouts on the deferred-collection feature whose status is `complete`. Omitted otherwise.", "anyOf": [ { "$ref": "#/components/schemas/PlatformFees" }, { "type": "null" } ] } }, "example": { "allow_promotion_codes": false, "amount_total": 2500, "amount_subtotal": 2500, "amount_received": 2500, "amount_refunded": 2500, "amount_disputed": 2500, "cancel_url": "https://example.com", "captures": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "disputes": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "capture_method": "automatic", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "example_value", "created_at": 2500, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "expires_at": 2500, "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "hsa_fsa_eligible": false, "letter_of_medical_necessity_required": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "mode": "payment", "origin": "shopify", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intents": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "redirect_url": "https://example.com", "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "shipping_address_collection": false, "shipping_details": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "open", "success_url": "https://example.com", "fees": [ { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } }, "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription_data": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "test_mode": false, "total_details": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "visit_type": "cbtSleep", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "next_action": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "selling_plans": [ { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } ], "shopify_payment_details": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } }, "renewal_as_of": 1781533800, "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "platform_fees": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } } }, "Expandable_for_V1Capture": { "anyOf": [ { "type": "string", "example": "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/V1Capture" } ], "description": "An expandable field — either a string ID or an expanded V1Capture object.", "example": "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "V1Capture": { "description": "A capture represents a charge that has been captured from a customer's account. You can capture a charge in full or in part.", "type": "object", "required": [ "amount_captured", "capture_id", "created_at", "items", "test_mode" ], "properties": { "amount_captured": { "description": "The total amount captured from the capture request", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_shipping_captured": { "description": "The shipping amount captured", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_discount_captured": { "description": "The discount amount captured", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_tax_captured": { "description": "The tax amount captured", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "capture_id": { "description": "The unique identifier for the capture.", "type": "string", "example": "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "created_at": { "description": "The created at timestamp for the capture", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "items": { "description": "The items associated with the capture", "type": "array", "items": { "$ref": "#/components/schemas/V1CaptureItem" } }, "metadata": { "description": "Metadata associated with the capture", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": { "order_id": "8842", "channel": "shopify" } }, "test_mode": { "description": "Whether the capture is in test mode", "type": "boolean", "example": false } }, "example": { "amount_captured": 2500, "amount_shipping_captured": 2500, "amount_discount_captured": 2500, "amount_tax_captured": 2500, "capture_id": "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "amount_captured": 2500, "capture_item_id": "fcapi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false } ], "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false } }, "V1CaptureItem": { "description": "A CaptureItem represents the portion of a single line item that was captured as part of a Capture, including the amount taken and the price and payment intent it was settled against.", "type": "object", "required": [ "amount_captured", "capture_item_id", "created_at", "test_mode" ], "properties": { "amount_captured": { "description": "The amount captured that is associated with this specific capture item", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "capture_item_id": { "description": "The unique identifier for the capture item.", "type": "string", "example": "fcapi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "created_at": { "description": "The created at timestamp for the capture item", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "price": { "description": "The price id associated with the capture item", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_Price" }, { "type": "null" } ] }, "payment_intent": { "description": "ID of the PaymentIntent that this capture item was settled against. `null` if no payment intent is associated with the item.", "type": [ "string", "null" ], "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "test_mode": { "description": "Whether the capture item is in test mode", "type": "boolean", "example": false } }, "example": { "amount_captured": 2500, "capture_item_id": "fcapi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false } }, "Expandable_for_Price": { "anyOf": [ { "type": "string", "example": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/Price" } ], "description": "An expandable field — either a string ID or an expanded Price object.", "example": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "Price": { "description": "Prices define the unit cost and (optional) billing cycle for both recurring and one-time purchases of products. Prices belong to a given product. Different physical goods or levels of service should be represented by products, and pricing options should be represented by prices.", "type": "object", "required": [ "active", "created_at", "price_id", "product", "test_mode", "type", "unit_amount" ], "properties": { "price_id": { "description": "The unique identifier for the price.", "type": "string", "example": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "owner_partner_id": { "description": "The ID of the account that owns this price. For prices shared across an organization this may be a sibling account; otherwise it is your own account ID.", "type": [ "string", "null" ], "example": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "description": { "description": "The description of the price.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" }, "trial_period_days": { "description": "The number of trial period days before the customer is first charged for a recurring price.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "unit_amount": { "description": "The amount to charge per unit, in the smallest currency unit (e.g., `2500` = $25.00 USD).", "type": "integer", "format": "int32", "minimum": -2147483648.0, "maximum": 2147483647.0 }, "recurring": { "description": "The recurring components of a price such as interval and trial period days.", "anyOf": [ { "$ref": "#/components/schemas/Recurring" }, { "type": "null" } ] }, "active": { "description": "Whether the price is currently active.", "type": "boolean", "example": false }, "product": { "description": "The product this price belongs to. Returned as a product ID by default, or as the full Product object when expanded.", "$ref": "#/components/schemas/Expandable_for_Product" }, "created_at": { "description": "The date the price was created.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "type": { "description": "The type of the price: a single one-time charge, or a recurring charge billed on a schedule.", "$ref": "#/components/schemas/PriceType" }, "metadata": { "description": "Metadata information for the price object", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "lookup_key": { "description": "A stable, partner-owned key for this price. Unique per account and mode across all prices, archived ones included. `null` until you set one.", "type": [ "string", "null" ], "maxLength": 200, "example": "standard_monthly" }, "hsa_fsa_eligibility": { "description": "The HSA/FSA eligibility for the price.", "anyOf": [ { "$ref": "#/components/schemas/HSAFSAElegibility" }, { "type": "null" } ] }, "test_mode": { "description": "Whether the price is in test mode.", "type": "boolean", "example": false } }, "example": { "price_id": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "trial_period_days": 0, "unit_amount": 0, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "active": false, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "type": "one_time", "metadata": { "order_id": "8842", "channel": "shopify" }, "lookup_key": "standard_monthly", "hsa_fsa_eligibility": "not_eligible", "test_mode": false } }, "Recurring": { "description": "Describes how a recurring price bills over time. Present on prices of type `recurring`; `null` for one-time prices.", "type": "object", "required": [ "interval" ], "properties": { "interval": { "description": "The billing cadence for the price.", "$ref": "#/components/schemas/RecurringInterval" }, "interval_count": { "description": "The number of intervals", "type": [ "integer", "null" ], "format": "int64", "minimum": 0.0, "maximum": 4294967295.0 }, "trial_period_days": { "description": "The number of trial period days before the customer is charged for the first time. Whole days only. For a precise trial-end timestamp (e.g. non-integer days), use `subscription_data.trial_end` on the Create Checkout Session request instead.", "type": [ "integer", "null" ], "format": "int64", "minimum": 0.0, "maximum": 4294967295.0 } }, "example": { "interval": "day", "interval_count": 0, "trial_period_days": 0 } }, "RecurringInterval": { "description": "The frequency at which a recurring price bills.", "type": "string", "enum": [ "day", "week", "month", "year" ], "example": "day" }, "Expandable_for_Product": { "anyOf": [ { "type": "string", "example": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/Product" } ], "description": "An expandable field — either a string ID or an expanded Product object.", "example": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "Product": { "description": "A Product defines what you sell. Flex determines its HSA/FSA eligibility from the name, description, and identifiers you provide.", "type": "object", "required": [ "active", "created_at", "hsa_fsa_eligibility", "name", "product_id", "test_mode" ], "properties": { "product_id": { "description": "The unique identifier for the product.", "type": "string", "example": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "owner_partner_id": { "description": "The ID of the account that owns this product. For products shared across an organization this may be a sibling account; otherwise it is your own account ID.", "type": [ "string", "null" ], "example": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "name": { "description": "The name of the product.", "type": "string", "example": "Example" }, "description": { "description": "The description of the product.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" }, "document_description": { "description": "Medical-grade description optimized for use in Letters of Medical Necessity and receipts.", "deprecated": true, "type": [ "string", "null" ] }, "receipt_description": { "description": "Shortened description tailored to receipt line items", "type": [ "string", "null" ] }, "created_at": { "description": "The date the product was created.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "visit_type": { "description": "The visit type of the product if a letter of medical necessity is required.", "anyOf": [ { "$ref": "#/components/schemas/VisitTypeName" }, { "type": "null" } ] }, "active": { "description": "Determines if the product is active or not.", "type": "boolean", "example": false }, "upc_code": { "description": "The upc code of the product.", "type": [ "string", "null" ] }, "gtin": { "description": "The gtin code of the product.", "type": [ "string", "null" ] }, "reference_gtin": { "description": "The GTIN of a private-label reference product, used to establish HSA/FSA eligibility.", "type": [ "string", "null" ] }, "hsa_fsa_eligibility": { "description": "The elegibility of the product for HSA/FSA.", "$ref": "#/components/schemas/HSAFSAElegibility" }, "test_mode": { "description": "Whether the product is in test mode or not.", "type": "boolean", "example": false }, "metadata": { "description": "Metadata associated with the product.", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": { "order_id": "8842", "channel": "shopify" } }, "url": { "description": "The URL of the product.", "type": [ "string", "null" ], "example": "https://example.com" }, "client_reference_id": { "description": "An optional identifier for the product set by the client at creation time. Immutable after creation.", "type": [ "string", "null" ], "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "example": { "product_id": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "document_description": "string", "receipt_description": "string", "created_at": "2026-06-15T14:30:00Z", "visit_type": "cbtSleep", "active": false, "upc_code": "string", "gtin": "string", "reference_gtin": "string", "hsa_fsa_eligibility": "not_eligible", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "VisitTypeName": { "description": "The name of the telehealth visit type.", "type": "string", "enum": [ "cbtSleep", "notApplicable", "metabolomics", "tinnitus", "gym", "exerciseDiet", "orthopedic", "alcohol", "airPurification", "vaginalHealth", "menstrual", "canopy", "alopecia", "genate", "weightBlanket", "bedJet", "siderAl", "sunwinkPowder", "wavWatch", "bodyComplete", "ageRate", "nitrousOxide", "happyV", "groupChat", "icalmAnxiety", "redBloom", "foodom", "branchErgonomicFurniture", "curalife", "eloraInfantWellness", "nutriHealth", "olipop", "goldIntimate", "touchStoneEssentials", "utiva", "sleepGeekz", "figBrew", "auBabyBlanket", "babySleepSack", "oshWellness", "currentBodyRedLight", "mito", "circularRing", "lymaRedLight", "goodAirRx", "tastermonial", "karunaHome", "ergoStandingChair", "jbaGlucoseControl", "bloomNutrition", "buoyDrops", "luxeWonderWig", "saunaMarketplace", "amrioreEyewear", "pivotOrthoShoe", "lumenCynergy", "roga", "pulsetto", "mitoRedLight", "gutPersonal", "goFlaus", "myHixel", "calmigo", "dotFit", "stripesBeauty", "mixHers", "pmd", "positivityWithPurpose", "techRing", "popVeneers", "vertaClean", "lumen", "medicalMeal", "emnHealth", "detergentAllergy", "lowImpactExercise", "mediumImpactExercise", "highImpactExercise", "gardening", "babyCarrier", "smartGlasses", "automatedCleaner", "uvClothing", "adaptiveShoes", "nonenalOdor", "babyMonitorSplit", "babySleepApp", "coolingSleepwear", "bodyPillow", "coolingBed", "posture", "supplements", "sleep", "redLightTherapy", "fitness", "smartRing", "womensVaginalHealth", "fertilitySupport", "femaleReproduction", "femaleReproductionFood", "pregnancyLiterature", "iceBath", "orthopedicShoes", "sexualHealth", "glucose", "metabolicTest", "skinCare", "oralHealth", "oralAnxiety", "blueLightGlasses", "anxiety", "brainHealth", "babyMonitor", "compressionSocks", "compressionShorts", "waterPurification", "medSpa", "essentialOils", "sleepBuds", "latchLight", "nutritionist", "rairflow", "enduranceTraining", "hydration", "hairGrowth", "eD", "postureFitness", "childDevelopment", "adaptiveClothing", "sleepConsulting", "hairRemoval", "menopause", "maleFertility", "anxietyHealth", "bidets", "speechHealth", "artOfLiving", "breastMilk", "breathWork", "petSupport", "diapers", "gutSupplements", "smartWatch", "medicalBotox", "biomechanicalAssessment", "erectileReset", "femaleOrgasm", "pornAddiction", "memorySupport", "oralHealthMasticGum", "orthopedicSandals", "childDevelopmentAnxietySleep", "childDevelopmentAdjustment", "childDevelopmentBehavior", "childDevelopmentIdentity", "emnHealthMobility", "adaptiveShoesDependent", "speechHealthDependent" ], "example": "cbtSleep" }, "HSAFSAElegibility": { "description": "How a product qualifies for HSA/FSA payment, which determines the substantiation required to pay with a benefits card. `pending` means the product is still awaiting Flex's automatic classification, so its eligibility is not yet determined.", "type": "string", "enum": [ "not_eligible", "auto_substantiation", "private_label", "letter_of_medical_necessity", "prescription", "vision", "service", "pending" ], "example": "not_eligible" }, "PriceType": { "description": "Whether the price is charged once or on a recurring schedule.", "type": "string", "enum": [ "one_time", "recurring" ], "example": "one_time" }, "Expandable_for_Dispute": { "anyOf": [ { "type": "string", "example": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/Dispute" } ], "description": "An expandable field — either a string ID or an expanded Dispute object.", "example": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "PaymentIntentCaptureMethod": { "description": "Controls when funds are captured: automatically once the payment is confirmed, or manually at a later time.", "type": "string", "enum": [ "automatic", "automatic_async", "manual" ], "example": "automatic" }, "Expandable_for_Customer": { "anyOf": [ { "type": "string", "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/Customer" } ], "description": "An expandable field — either a string ID or an expanded Customer object.", "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "CustomerDefaults": { "description": "Customer values used to prefill the customer details on the hosted checkout page.", "type": "object", "properties": { "customer_id": { "description": "ID of an existing Customer to associate with the session. When set, the customer's saved details are used instead of the other fields.", "type": [ "string", "null" ], "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "email": { "description": "The customer's email address, prefilled on the checkout page.", "type": [ "string", "null" ], "example": "john.doe@example.com" }, "first_name": { "description": "The customer's first name, prefilled on the checkout page.", "type": [ "string", "null" ], "example": "John" }, "last_name": { "description": "The customer's last name, prefilled on the checkout page.", "type": [ "string", "null" ], "example": "Doe" }, "phone": { "description": "The customer's phone number in E.164 format, prefilled on the checkout page.", "type": [ "string", "null" ], "example": "+14155550142" } }, "example": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" } }, "Mode": { "description": "The mode of the checkout session, which determines what happens on completion: a one-time payment, starting a subscription, charging a saved payment method off-session, or saving a payment method for future use. `reimbursement` is in limited release: it issues a letter for a purchase made elsewhere and charges only an explicit `lmn_consultation` fee. Checkout sessions return `mode_not_supported` for it unless it is enabled for your account; payment links always do.", "type": "string", "enum": [ "payment", "subscription", "off_session", "setup", "reimbursement" ], "example": "payment" }, "CheckoutSessionOrigin": { "description": "Origin of where the checkout session was generated", "type": "string", "enum": [ "shopify", "shopline", "prepurchase", "postpurchase", "renewal" ], "example": "shopify" }, "Expandable_for_PaymentIntent": { "anyOf": [ { "type": "string", "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/PaymentIntent" } ], "description": "An expandable field — either a string ID or an expanded PaymentIntent object.", "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "PaymentIntent": { "description": "A PaymentIntent tracks Flex's process of collecting a payment from a customer: the amount to collect, its lifecycle status, and references to the customer, payment method, and resulting charge. A single PaymentIntent may produce several charges over its lifetime (for example after a retry); the most recent is referenced by `latest_charge`.", "type": "object", "required": [ "amount", "capture_method", "created_at", "payment_intent_id", "status", "test_mode" ], "properties": { "payment_intent_id": { "description": "The unique identifier for the payment intent.", "type": "string", "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "amount": { "description": "The amount of the payment intent in cents.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_capturable": { "description": "The amount that can be captured from this PaymentIntent.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_received": { "description": "The amount that was received in cents.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "application_fee_amount": { "description": "The amount of the Flex application fee.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "customer": { "description": "The customer associated with the payment intent.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_Customer" }, { "type": "null" } ] }, "transfer_data": { "description": "The data related to the amount being transferred.", "anyOf": [ { "$ref": "#/components/schemas/TransferData" }, { "type": "null" } ] }, "status": { "description": "The status of the payment intent.", "$ref": "#/components/schemas/PaymentIntentStatus" }, "latest_charge": { "description": "The latest charge associated with the payment intent.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_Charge" }, { "type": "null" } ] }, "created_at": { "description": "The time the payment intent was created.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "invoice": { "description": "The invoice associated with the payment intent.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_Invoice" }, { "type": "null" } ] }, "capture_method": { "description": "The capture method of the payment intent.", "$ref": "#/components/schemas/PaymentIntentCaptureMethod" }, "client_secret": { "description": "The client secret of the payment intent.", "type": [ "string", "null" ] }, "metadata": { "description": "The metadata associated with the payment intent.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "payment_method": { "description": "The payment method associated with the payment intent.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_PaymentMethod" }, { "type": "null" } ] }, "test_mode": { "description": "Whether the payment intent is in test mode.", "type": "boolean", "example": false }, "transfer_group": { "description": "A string that identifies the resulting payment as part of a group", "type": [ "string", "null" ], "example": "example_value" }, "payment_card_type": { "description": "The primary card type used for this payment intent", "anyOf": [ { "$ref": "#/components/schemas/PaymentCardType" }, { "type": "null" } ] }, "letter_fee_amount": { "description": "Letter fee portion of application_fee_amount (waterfall allocation to HSA/FSA)", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "transaction_fee": { "description": "Transaction fee portion of application_fee_amount (percentage + fixed fee)", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "last_payment_error": { "description": "The error from the most recent failed payment attempt, if any.", "anyOf": [ { "$ref": "#/components/schemas/LastPaymentError" }, { "type": "null" } ] } }, "example": { "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "amount_capturable": 2500, "amount_received": 2500, "application_fee_amount": 0, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "transfer_data": { "amount": 2500, "destination": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "status": "canceled", "latest_charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "capture_method": "automatic", "client_secret": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "transfer_group": "example_value", "payment_card_type": "primary", "letter_fee_amount": 0, "transaction_fee": 0, "last_payment_error": { "type": "string", "code": "string", "decline_code": "string", "message": "string", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } }, "TransferData": { "description": "Describes how funds collected by a PaymentIntent are routed to your account. Present only when the payment carries an application fee or an explicit transfer amount.", "type": "object", "required": [ "destination" ], "properties": { "amount": { "description": "The amount to transfer, in cents.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "destination": { "description": "The destination account of the transfer.", "type": "string", "example": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "example": { "amount": 2500, "destination": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "PaymentIntentStatus": { "description": "The current lifecycle status of the payment intent.", "type": "string", "enum": [ "canceled", "processing", "requires_action", "requires_capture", "requires_confirmation", "requires_payment_method", "succeeded" ], "example": "canceled" }, "Expandable_for_Charge": { "anyOf": [ { "type": "string", "example": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/Charge" } ], "description": "An expandable field — either a string ID or an expanded Charge object.", "example": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "Charge": { "description": "A Charge represents a single attempt to move funds for a payment, including its outcome and any 3D Secure, decline, and risk details. A PaymentIntent can have multiple charges over its lifetime (for example after a retry); the most recent is referenced by the PaymentIntent's `latest_charge`.", "type": "object", "required": [ "amount", "amount_captured", "amount_refunded", "captured", "charge_id", "created_at", "disputed", "paid", "payment_intent", "refunded", "status", "test_mode" ], "properties": { "charge_id": { "description": "Unique identifier for the charge.", "type": "string", "example": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "amount": { "description": "Amount intended to be collected by this payment.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_captured": { "description": "Amount in cents captured (can be less than the amount attribute on the charge if a partial capture was made).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_refunded": { "description": "Amount in cents refunded (can be less than the amount attribute on the charge if a partial refund was made).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "application_fee_amount": { "description": "The Flex application fee for the charge", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "captured": { "description": "If the charge was created without capturing, this Boolean represents whether it is still uncaptured or has since been captured.", "type": "boolean", "example": false }, "created_at": { "description": "Time at which the object was created. ISO 8601 format.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "customer": { "description": "The customer this charge is for if one exists.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_Customer" }, { "type": "null" } ] }, "invoice": { "description": "The invoice this charge is for if one exists.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_Invoice" }, { "type": "null" } ] }, "failure_message": { "description": "Message to user further explaining reason for charge failure if available.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" }, "disputed": { "description": "Whether the charge has been disputed.", "type": "boolean", "example": false }, "paid": { "description": "true if the charge succeeded, or was successfully authorized for later capture.", "type": "boolean", "example": false }, "refunded": { "description": "Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.", "type": "boolean", "example": false }, "refunds": { "description": "A list of refunds that have been applied to the charge.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Expandable_for_Refund" } }, "payment_intent": { "description": "The payment intent that generated this charge.", "$ref": "#/components/schemas/Expandable_for_PaymentIntent" }, "status": { "description": "The status of the charge.", "$ref": "#/components/schemas/ChargeStatus" }, "test_mode": { "description": "Whether the charge was created in test mode.", "type": "boolean", "example": false }, "transfer_group": { "description": "A string that identifies the resulting payment as part of a group", "type": [ "string", "null" ], "example": "example_value" }, "payment_method_id": { "description": "The ID of the PaymentMethod.", "type": [ "string", "null" ], "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "three_d_secure": { "description": "3D Secure authentication outcome details, if 3DS was used.", "anyOf": [ { "$ref": "#/components/schemas/ThreeDSecureOutcome" }, { "type": "null" } ] }, "decline_details": { "description": "Decline and risk details for failed or blocked charges.", "anyOf": [ { "$ref": "#/components/schemas/DeclineDetails" }, { "type": "null" } ] }, "balance_transaction": { "description": "Balance transaction that describes the impact of this charge on your balance. Populated on successful capture, returned as the balance transaction ID. Always serialized; `null` for uncaptured charges.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_BalanceTransaction" }, { "type": "null" } ] }, "failure_balance_transaction": { "description": "Reversal balance transaction created when a captured charge fails or is otherwise reversed and funds are credited back. Always serialized; `null` on the common success path.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_BalanceTransaction" }, { "type": "null" } ] } }, "example": { "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "amount_captured": 2500, "amount_refunded": 2500, "application_fee_amount": 0, "captured": false, "created_at": "2026-06-15T14:30:00Z", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_message": "Premium SPF 50 mineral sunscreen", "disputed": false, "paid": false, "refunded": false, "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "succeeded", "test_mode": false, "transfer_group": "example_value", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "three_d_secure": { "authentication_flow": "string", "result": "string", "result_reason": "string", "version": "string" }, "decline_details": { "failure_code": "string", "decline_code": "string", "failure_message": "string", "outcome_type": "string", "network_status": "string", "seller_message": "string", "reason": "string", "risk_level": "string" }, "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "Expandable_for_Invoice": { "anyOf": [ { "type": "string", "example": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/Invoice" } ], "description": "An expandable field — either a string ID or an expanded Invoice object.", "example": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "Invoice": { "description": "An Invoice is a statement of the amounts owed by a customer, generated when a subscription advances through its billing cycle. It tracks the total, amount due, and amount paid, along with the payment intent, charge, and billing period that produced it, and its current lifecycle status as it is finalized and collected.", "type": "object", "required": [ "amount_due", "amount_paid", "collection_method", "created_at", "invoice_id", "status", "test_mode", "total" ], "properties": { "invoice_id": { "description": "The id of the invoice.", "type": "string", "example": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "total": { "description": "The total amount of the invoice in cents.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_due": { "description": "The amount due in cents.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_paid": { "description": "The amount paid in cents.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "payment_intent": { "description": "The payment intent associated with this invoice. The payment intent is created when the invoice is finalized.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_PaymentIntent" }, { "type": "null" } ] }, "charge": { "description": "The id of the latest charge for this invoice.", "type": [ "string", "null" ], "example": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "customer": { "description": "The id of the customer this invoice is for.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_Customer" }, { "type": "null" } ] }, "period_end": { "description": "End of the usage period.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "period_start": { "description": "Start of the usage period.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "subscription": { "description": "The subscription that this invoice was prepared for.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_Subscription" }, { "type": "null" } ] }, "paid_at": { "description": "When the invoice was paid.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "status": { "description": "The status of the invoice.", "$ref": "#/components/schemas/InvoiceStatus" }, "collection_method": { "description": "Either charge_automatically or send_invoice. When charging automatically, Flex will attempt to pay this invoice using the default payment method attached to the customer. When sending an invoice, Flex will email this invoice to the customer with payment instructions.", "$ref": "#/components/schemas/CollectionMethod" }, "test_mode": { "description": "Whether or not the invoice was created in test mode.", "type": "boolean", "example": false }, "metadata": { "description": "Metadata associated with the invoice.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "created_at": { "description": "When the invoice was created.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "backup_charge_status": { "description": "Outcome of the backup-payment-method fallback for this invoice. Omitted when no fallback applied. `succeeded` on a paid invoice means the subscription's backup card covered this renewal after the default payment method failed.", "anyOf": [ { "$ref": "#/components/schemas/BackupChargeStatus" }, { "type": "null" } ] } }, "example": { "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "total": 2500, "amount_due": 2500, "amount_paid": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "period_end": "string", "period_start": "string", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "paid_at": "string", "status": "draft", "collection_method": "charge_automatically", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "backup_charge_status": "pending" } }, "Expandable_for_Subscription": { "anyOf": [ { "type": "string", "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/Subscription" } ], "description": "An expandable field — either a string ID or an expanded Subscription object.", "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "Subscription": { "description": "A Subscription represents a recurring billing arrangement that charges a customer at a fixed interval. It tracks the items being billed, the current billing period, its lifecycle status, and the invoices it generates each cycle.", "type": "object", "required": [ "cancel_at_period_end", "created_at", "items", "status", "subscription_id", "test_mode" ], "properties": { "subscription_id": { "description": "Unique identifier for the object.", "type": "string", "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "created_at": { "description": "Time at which the object was created. ISO 8601 format.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "items": { "description": "The items the customer is subscribed to.", "type": "array", "items": { "$ref": "#/components/schemas/V1SubscriptionItem" } }, "latest_invoice": { "description": "The ID of the latest invoice generated for this subscription.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_Invoice" }, { "type": "null" } ] }, "customer": { "description": "The ID of the customer who owns the subscription.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_Customer" }, { "type": "null" } ] }, "status": { "description": "Possible values are incomplete, incomplete_expired, trialing, active, past_due, canceled, unpaid, or paused.", "$ref": "#/components/schemas/SubscriptionStatus" }, "cancel_at_period_end": { "description": "If the subscription has been canceled with the at_period_end flag set to true, cancel_at_period_end on the subscription will be true. You can use this attribute to determine whether a subscription that has a status of active is scheduled to be canceled at the end of the current period.", "type": "boolean", "example": false }, "current_period_end": { "description": "End of the current period that the subscription has been invoiced for.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "current_period_start": { "description": "Start of the current period that the subscription has been invoiced for.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "metadata": { "description": "A set of key/value pairs that you can attach to a subscription object.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "test_mode": { "description": "Whether the subscription is in test mode.", "type": "boolean", "example": false }, "client_secret": { "description": "Client secrets used to confirm the subscription's first payment or payment-method setup from your frontend. Present only while the subscription is being activated; omitted otherwise. Do not log or store these secrets; expose them only to the customer over TLS.", "anyOf": [ { "$ref": "#/components/schemas/SubscriptionClientSecret" }, { "type": "null" } ] }, "proration_behavior": { "description": "The proration behavior for the subscription.", "anyOf": [ { "$ref": "#/components/schemas/FlexSubscriptionProrationBehavior" }, { "type": "null" } ] }, "trial_start": { "description": "Start of the subscription's trial period, as an RFC 3339 timestamp. `null` if the subscription has no trial.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "trial_end": { "description": "End of the subscription's trial period, as an RFC 3339 timestamp. After this time the customer is billed normally. `null` if the subscription has no trial.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "cancel_at": { "description": "A future RFC 3339 timestamp at which the subscription will automatically be canceled. `null` unless a future cancellation has been scheduled.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" }, "canceled_at": { "description": "The RFC 3339 timestamp at which the subscription was actually canceled. `null` if the subscription has not been canceled. Unlike `cancel_at` (a future scheduled cancellation), this is set once the cancellation has occurred.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" }, "default_payment_method": { "description": "The default payment method for the subscription (expandable).", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_PaymentMethod" }, { "type": "null" } ] }, "backup_payment_method": { "description": "The payment method charged when the default one fails (expandable). Omitted when the subscription has no backup.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_PaymentMethod" }, { "type": "null" } ] }, "discounts": { "description": "The discounts applied to the subscription. Only present when `expand=discounts` is requested; omitted from the response otherwise. Usually 0–1 elements (Flex applies at most one coupon per subscription today), but modeled as an array for Stripe parity and future multi-discount support.\n\nFull `Discount` objects rather than `Expandable`: unlike the other expandable fields, `discounts` is populated only on `expand=discounts` and is always hydrated, so it never serializes as a bare ID. (The nested `source.coupon` inside each discount is still an `Expandable`, honoring `expand=discounts,coupons`.)", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Discount" } }, "pause": { "description": "The current pause. Present only while the subscription is paused.", "anyOf": [ { "$ref": "#/components/schemas/SubscriptionPause" }, { "type": "null" } ] } }, "example": { "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "quantity": 2500, "created_at": "2026-06-15T14:30:00Z", "updated_at": "2026-06-15T14:30:00Z", "test_mode": false } ], "latest_invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "incomplete", "cancel_at_period_end": false, "current_period_end": "string", "current_period_start": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false, "client_secret": { "setup_secret": "string", "payment_secret": "string" }, "proration_behavior": "always_invoice", "trial_start": "string", "trial_end": "string", "cancel_at": "2026-06-15T14:30:00Z", "canceled_at": "2026-06-15T14:30:00Z", "default_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "discounts": [ { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } ], "pause": { "paused_at": "2026-06-15T14:30:00Z", "resume_at": "2026-06-15T14:30:00Z" } } }, "V1SubscriptionItem": { "description": "A Subscription Item represents a single recurring Price billed as part of a Subscription, together with the quantity of that price the customer is subscribed to. A subscription has one item per recurring price it bills.", "type": "object", "required": [ "created_at", "price", "quantity", "subscription_item_id", "test_mode" ], "properties": { "subscription_item_id": { "description": "Unique identifier for the subscription item.", "type": "string", "example": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "price": { "description": "The recurring Price this item bills. Returned as a price ID by default, or as the full Price object when expanded.", "$ref": "#/components/schemas/Expandable_for_Price" }, "quantity": { "description": "The number of units of the price the customer is subscribed to.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "created_at": { "description": "Time at which the subscription item was created, as an RFC 3339 timestamp.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "updated_at": { "description": "Time at which the subscription item was last updated, as an RFC 3339 timestamp. `null` if the item has not been updated since creation.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" }, "test_mode": { "description": "Whether the subscription item exists in test mode.", "type": "boolean", "example": false } }, "example": { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "quantity": 2500, "created_at": "2026-06-15T14:30:00Z", "updated_at": "2026-06-15T14:30:00Z", "test_mode": false } }, "SubscriptionStatus": { "description": "The current lifecycle status of the subscription.", "type": "string", "enum": [ "incomplete", "incomplete_expired", "trialing", "active", "past_due", "canceled", "unpaid", "paused" ], "example": "incomplete" }, "SubscriptionClientSecret": { "description": "Client secrets used to confirm the subscription's first payment or payment-method setup from your frontend. Present only while the subscription is being activated.", "type": "object", "properties": { "setup_secret": { "description": "Client secret of the SetupIntent used to collect and save a payment method for the subscription (for example, during a trial with no immediate charge). `null` when no setup is required. Do not log or store it; expose only to the customer over TLS.", "type": [ "string", "null" ] }, "payment_secret": { "description": "Client secret of the PaymentIntent used to confirm the subscription's first payment from your frontend. `null` when no immediate payment is required. Do not log or store it; expose only to the customer over TLS.", "type": [ "string", "null" ] } }, "example": { "setup_secret": "string", "payment_secret": "string" } }, "FlexSubscriptionProrationBehavior": { "description": "How proration is handled when the subscription changes mid-billing-cycle.", "type": "string", "enum": [ "always_invoice", "create_prorations", "none" ], "example": "always_invoice" }, "Expandable_for_PaymentMethod": { "anyOf": [ { "type": "string", "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/PaymentMethod" } ], "description": "An expandable field — either a string ID or an expanded PaymentMethod object.", "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "PaymentMethod": { "description": "A PaymentMethod object represents a customer's payment instrument (such as a card) that can be used to collect payments. Attach it to a Customer to reuse it across checkout sessions, invoices, and subscriptions.", "type": "object", "required": [ "billing_details", "card", "created_at", "customer", "off_session", "payment_method_id", "test_mode" ], "properties": { "payment_method_id": { "description": "The ID of the PaymentMethod.", "type": "string", "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "billing_details": { "description": "Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.", "$ref": "#/components/schemas/BillingDetails" }, "customer": { "description": "The customer this payment method is attached to. Returned as the customer ID by default; expandable to the full Customer object.", "$ref": "#/components/schemas/Expandable_for_Customer" }, "metadata": { "description": "Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.", "type": [ "object", "null" ], "additionalProperties": { "type": "object" }, "example": { "order_id": "8842", "channel": "shopify" } }, "card": { "description": "User card details.", "$ref": "#/components/schemas/Card" }, "created_at": { "description": "Time at which the object was created. ISO 8601 format.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "test_mode": { "description": "Whether this PaymentMethod is in test mode.", "type": "boolean", "example": false }, "off_session": { "description": "Whether this PaymentMethod is valid for off_session (customer not present) purchase flows.", "type": "boolean" } }, "example": { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "billing_details": { "address": { "city": "San Francisco", "country": "US", "line1": "123 Main St", "line2": "Suite 100", "postal_code": "94107", "state": "CA" }, "email": "john.doe@example.com", "name": "Example", "phone": "+14155550142" }, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "card": { "brand": "american_express", "country": "US", "exp_month": 12, "exp_year": 2027, "fingerprint": "abc123", "funding": "credit", "last4": "4242" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "off_session": true } }, "BillingDetails": { "description": "Billing information associated with a PaymentMethod, such as the cardholder's billing address, email, name, and phone number.", "type": "object", "properties": { "address": { "description": "The billing address.", "anyOf": [ { "$ref": "#/components/schemas/BillingAddress" }, { "type": "null" } ] }, "email": { "description": "The billing email address.", "type": [ "string", "null" ], "example": "john.doe@example.com" }, "name": { "description": "The billing name.", "type": [ "string", "null" ], "example": "Example" }, "phone": { "description": "The billing phone number.", "type": [ "string", "null" ], "example": "+14155550142" } }, "example": { "address": { "city": "San Francisco", "country": "US", "line1": "123 Main St", "line2": "Suite 100", "postal_code": "94107", "state": "CA" }, "email": "john.doe@example.com", "name": "Example", "phone": "+14155550142" } }, "BillingAddress": { "description": "A billing address attached to a PaymentMethod's billing details.", "type": "object", "properties": { "city": { "description": "City, district, suburb, town, or village.", "type": [ "string", "null" ], "example": "San Francisco" }, "country": { "description": "Two-letter ISO country code (e.g., `US`).", "type": [ "string", "null" ], "example": "US" }, "line1": { "description": "Address line 1, such as the street, PO box, or company name.", "type": [ "string", "null" ], "example": "123 Main St" }, "line2": { "description": "Address line 2, such as the apartment, suite, unit, or building.", "type": [ "string", "null" ], "example": "Suite 100" }, "postal_code": { "description": "ZIP or postal code.", "type": [ "string", "null" ], "example": "94107" }, "state": { "description": "State, county, province, or region.", "type": [ "string", "null" ], "example": "CA" } }, "example": { "city": "San Francisco", "country": "US", "line1": "123 Main St", "line2": "Suite 100", "postal_code": "94107", "state": "CA" } }, "Card": { "description": "A Card object describes the card backing a PaymentMethod, including its brand, funding type, expiration, and the last four digits.", "type": "object", "required": [ "brand", "country", "exp_month", "exp_year", "fingerprint", "funding", "last4" ], "properties": { "brand": { "description": "The brand of the card.", "$ref": "#/components/schemas/CardBrand" }, "country": { "description": "Two-letter ISO code for the card's country.", "type": "string", "example": "US" }, "exp_month": { "description": "The card's expiration month.", "type": "integer", "format": "int32", "example": 12, "minimum": -128.0, "maximum": 127.0 }, "exp_year": { "description": "The card's expiration year.", "type": "integer", "format": "int32", "example": 2027, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "fingerprint": { "description": "Uniquely identifies this particular card number. You can use this attribute to check whether two customers who've signed up with you are using the same card.", "type": "string", "example": "abc123" }, "funding": { "description": "The funding type of the card.", "$ref": "#/components/schemas/CardFunding" }, "last4": { "description": "The last four digits of the card.", "type": "string", "example": "4242" } }, "example": { "brand": "american_express", "country": "US", "exp_month": 12, "exp_year": 2027, "fingerprint": "abc123", "funding": "credit", "last4": "4242" } }, "CardBrand": { "description": "The card's network (brand).", "type": "string", "enum": [ "american_express", "diners_club", "discover", "eftpos_au", "JCB", "master_card", "union_pay", "visa", "unknown" ], "example": "american_express" }, "CardFunding": { "description": "The card's funding type, such as credit, debit, prepaid, or an HSA/FSA benefits card.", "type": "string", "enum": [ "credit", "debit", "hsa_fsa", "prepaid", "unknown" ], "example": "credit" }, "Discount": { "description": "A Discount object represents the application of a coupon or promotion code to a checkout session, customer, subscription, or invoice. It records which coupon was redeemed, what the discount was applied to, and the time window over which it applies.", "type": "object", "required": [ "discount_id", "source", "start", "test_mode" ], "properties": { "discount_id": { "description": "The ID of the discount.", "type": "string", "example": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "description": "The checkout session that the discount was applied to.", "type": [ "string", "null" ], "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "customer": { "description": "The customer that the discount was applied to.", "type": [ "string", "null" ], "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "subscription": { "description": "The subscription that the discount was applied to.", "type": [ "string", "null" ], "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "invoice": { "description": "The invoice that the discount was applied to.", "type": [ "string", "null" ], "example": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "source": { "description": "The source of the discount (coupon or promotion code).", "$ref": "#/components/schemas/DiscountSource" }, "promo_code": { "description": "The promo code applied to create the discount.", "type": [ "string", "null" ], "example": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "test_mode": { "description": "Whether the discount was applied in test mode", "type": "boolean", "example": false }, "end": { "description": "If the coupon has a duration of repeating, the date that this discount will end. If the coupon has a duration of once or forever, this attribute will be null.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "start": { "description": "Date that the coupon was applied.", "$ref": "#/components/schemas/Timestamptz" } }, "example": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } }, "DiscountSource": { "description": "The source of a discount (coupon or promotion code).", "type": "object", "required": [ "coupon", "type" ], "properties": { "coupon": { "description": "The coupon that was redeemed. Returned as a coupon ID by default; pass `expand=discounts,coupons` on the Subscription API to expand it to the full coupon object.", "$ref": "#/components/schemas/Expandable_for_V1Coupon" }, "type": { "description": "The type of source.", "$ref": "#/components/schemas/DiscountSourceType" } }, "example": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" } }, "Expandable_for_V1Coupon": { "anyOf": [ { "type": "string", "example": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/V1Coupon" } ], "description": "An expandable field — either a string ID or an expanded V1Coupon object.", "example": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "V1Coupon": { "description": "A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. Coupons may be applied to subscriptions and checkout sessions.", "type": "object", "required": [ "coupon_id", "created_at", "duration", "name", "test_mode", "valid" ], "properties": { "coupon_id": { "description": "Unique identifier for the object.", "type": "string", "example": "fcoup_1234567890" }, "amount_off": { "description": "Amount that will be taken off the subtotal of any invoices for this customer.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "applies_to": { "description": "An object containing the ID of the product that the coupon can be applied to.", "anyOf": [ { "$ref": "#/components/schemas/AppliesTo" }, { "type": "null" } ] }, "duration": { "description": "One of forever, once, and repeating. Describes how long a customer who applies this coupon will get the discount.", "$ref": "#/components/schemas/CouponDuration" }, "duration_in_months": { "description": "If duration is repeating, the number of months the coupon applies. Null if coupon duration is forever or once.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "metadata": { "description": "Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "name": { "description": "Name of the coupon displayed to customers.", "type": "string", "example": "Example" }, "percent_off": { "description": "Percent that will be taken off the subtotal of any invoices for this customer for the duration of the coupon.", "type": [ "number", "null" ], "format": "double" }, "max_redemptions": { "description": "Maximum number of times this coupon can be redeemed, in total, across all customers, before it is no longer valid.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "times_redeemed": { "description": "Number of times this coupon has been applied to a customer.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "valid": { "description": "Taking account of the above properties, whether this coupon can still be applied to a customer.", "type": "boolean", "example": false }, "created_at": { "description": "Date when this coupon was created.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "test_mode": { "description": "Whether the coupon is in test mode", "type": "boolean", "example": false } }, "example": { "coupon_id": "fcoup_1234567890", "amount_off": 2500, "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "duration": "once", "duration_in_months": 0, "metadata": { "order_id": "8842", "channel": "shopify" }, "name": "Example", "percent_off": 0.0, "max_redemptions": 0, "times_redeemed": 0, "valid": false, "created_at": "2026-06-15T14:30:00Z", "test_mode": false } }, "AppliesTo": { "description": "What a coupon's discount is restricted to.", "anyOf": [ { "type": "object", "required": [ "products" ], "properties": { "products": { "description": "The product that this coupon applies to.", "type": "array", "items": { "type": "string", "example": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } }, { "type": "object", "required": [ "prices" ], "properties": { "prices": { "description": "The price that this coupon applies to.", "type": "array", "items": { "type": "string", "example": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } }, { "type": "object", "required": [ "fee_types" ], "properties": { "fee_types": { "description": "The fee types that this coupon applies to.", "type": "array", "items": { "$ref": "#/components/schemas/FeeType" } } } }, { "$ref": "#/components/schemas/AppliesToShipping" } ], "example": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] } }, "FeeType": { "description": "The kind of fee applied to a checkout session: a Letter of Medical Necessity consultation fee, or a custom fee you define.", "type": "string", "enum": [ "lmn_consultation", "custom" ], "example": "lmn_consultation" }, "AppliesToShipping": { "description": "The coupon applies to shipping.", "type": "string", "enum": [ "shipping" ], "example": "shipping" }, "CouponDuration": { "type": "string", "enum": [ "once", "repeating", "forever" ], "x-ms-enum": { "name": "CouponDuration", "modelAsString": false, "values": [ { "value": "once", "name": "Once", "description": "Applies to the first charge from a subscription with this coupon applied." }, { "value": "repeating", "name": "Repeating", "description": "Applies to charges in the first duration_in_months months from a subscription with this coupon applied." }, { "value": "forever", "name": "Forever", "description": "Applies to all charges from a subscription with this coupon applied." } ] }, "description": "- `once`: Applies to the first charge from a subscription with this coupon applied.\n- `repeating`: Applies to charges in the first duration_in_months months from a subscription with this coupon applied.\n- `forever`: Applies to all charges from a subscription with this coupon applied.", "example": "once" }, "DiscountSourceType": { "description": "The type of discount source.", "type": "string", "enum": [ "coupon", "promotion_code" ], "example": "coupon" }, "SubscriptionPause": { "description": "The pause a paused subscription is in.", "type": "object", "required": [ "paused_at" ], "properties": { "paused_at": { "description": "When the subscription was paused. ISO 8601 format. While paused, this is also the subscription's `current_period_end`.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "resume_at": { "description": "When Flex resumes the subscription on its own. `null` when it stays paused until you resume it.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" } }, "example": { "paused_at": "2026-06-15T14:30:00Z", "resume_at": "2026-06-15T14:30:00Z" } }, "InvoiceStatus": { "description": "The lifecycle status of the invoice.", "type": "string", "enum": [ "draft", "open", "void", "paid", "uncollectible" ], "example": "draft" }, "CollectionMethod": { "description": "How payment for the invoice is collected: automatically from the customer's saved payment method, or by emailing them an invoice to pay.", "type": "string", "enum": [ "charge_automatically", "send_invoice" ], "example": "charge_automatically" }, "BackupChargeStatus": { "description": "Outcome of charging a subscription's backup payment method for an invoice. `Pending` is written before the Stripe call, `Succeeded`/`Failed` after it, and `Skipped` when the invoice was no longer open by the time the fallback ran.", "type": "string", "enum": [ "pending", "succeeded", "failed", "skipped" ], "example": "pending" }, "Expandable_for_Refund": { "anyOf": [ { "type": "string", "example": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/Refund" } ], "description": "An expandable field — either a string ID or an expanded Refund object.", "example": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "Refund": { "description": "A Refund object represents the return of funds for a previously succeeded payment, in whole or in part. Issuing a refund reverses the corresponding charge(s) on the customer's HSA/FSA and/or credit card payment methods.", "type": "object", "required": [ "amount", "created_at", "refund_id", "status", "test_mode" ], "properties": { "refund_id": { "description": "The ID of the refund", "type": "string", "example": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "payment_intent_id": { "description": "The ID of the payment intent that the refund is associated with", "type": [ "string", "null" ], "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "amount": { "description": "The amount of the refund in cents", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "created_at": { "description": "The time at which the refund was created. ISO 8601 format.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "reason": { "description": "The reason for the refund", "anyOf": [ { "$ref": "#/components/schemas/RefundReason" }, { "type": "null" } ] }, "status": { "description": "The status of the refund", "$ref": "#/components/schemas/RefundStatus" }, "test_mode": { "description": "Whether the refund was created in test mode", "type": "boolean", "example": false }, "metadata": { "description": "Metadata attached to the refund", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": { "order_id": "8842", "channel": "shopify" } }, "reference_id": { "description": "Reference number that the customer can use to trace this refund with their bank or card issuer.", "type": [ "string", "null" ], "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "reference_type": { "description": "Type of the reference number used for the refund", "anyOf": [ { "$ref": "#/components/schemas/ReferenceType" }, { "type": "null" } ] }, "reference_status": { "description": "Status of the reference number used for the refund", "anyOf": [ { "$ref": "#/components/schemas/ReferenceStatus" }, { "type": "null" } ] }, "items": { "description": "List of refund items (charges that were refunded)", "default": [], "type": "array", "items": { "$ref": "#/components/schemas/RefundItem" } }, "subscription_id": { "description": "The subscription this refund is associated with (for subscription cancellation refunds)", "type": [ "string", "null" ], "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "invoice_id": { "description": "The invoice this refund is associated with (for subscription billing period refunds)", "type": [ "string", "null" ], "example": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "balance_transaction": { "description": "Balance transaction that describes the impact of this refund on your balance. Defaults to the balance transaction ID; use `?expand=balance_transaction` to inflate the full object.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_BalanceTransaction" }, { "type": "null" } ] }, "failure_balance_transaction": { "description": "After a refund fails, the balance transaction describing the adjustment that returns the funds to your balance.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_BalanceTransaction" }, { "type": "null" } ] } }, "example": { "refund_id": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "created_at": "2026-06-15T14:30:00Z", "reason": "duplicate", "status": "pending", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available", "items": [ { "amount_refunded": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available" } ], "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "RefundReason": { "description": "The reason the refund was issued.", "type": "string", "enum": [ "duplicate", "fraudulent", "requested_by_customer", "expired_uncaptured_charge" ], "example": "duplicate" }, "RefundStatus": { "description": "The current status of the refund.", "type": "string", "enum": [ "pending", "requires_action", "succeeded", "failed", "canceled" ], "example": "pending" }, "ReferenceType": { "description": "The kind of reference number associated with the refund.", "type": "string", "enum": [ "acquirer_reference_number", "system_trace_audit_number", "retrieval_reference_number" ], "example": "acquirer_reference_number" }, "ReferenceStatus": { "description": "The status of the refund's acquirer reference.", "type": "string", "enum": [ "available", "pending", "unavailable" ], "example": "available" }, "RefundItem": { "description": "Represents a single refund item (charge that was refunded)", "type": "object", "required": [ "amount_refunded" ], "properties": { "amount_refunded": { "description": "The amount refunded from this charge in cents", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "payment_intent": { "description": "The ID of the payment intent that the refund is associated with", "type": [ "string", "null" ], "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "payment_method_id": { "description": "The ID of the payment method used for this refund", "type": [ "string", "null" ], "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "reference_id": { "description": "Reference number that the customer can use to trace this refund with their bank or card issuer.", "type": [ "string", "null" ], "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "reference_type": { "description": "Type of the reference number used for the refund", "anyOf": [ { "$ref": "#/components/schemas/ReferenceType" }, { "type": "null" } ] }, "reference_status": { "description": "Status of the reference number used for the refund", "anyOf": [ { "$ref": "#/components/schemas/ReferenceStatus" }, { "type": "null" } ] } }, "example": { "amount_refunded": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available" } }, "Expandable_for_BalanceTransaction": { "anyOf": [ { "type": "string", "example": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/BalanceTransaction" } ], "description": "An expandable field — either a string ID or an expanded BalanceTransaction object.", "example": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "BalanceTransaction": { "description": "A BalanceTransaction represents a single change to your Flex account balance — for example, a charge, refund, dispute, fee, or payout. Each transaction records how much was added or removed, the processing fee, and the resulting net effect on your balance, and links back to the Flex object that caused it.", "type": "object", "required": [ "amount", "balance_transaction_id", "fee", "net", "status", "test_mode" ], "properties": { "balance_transaction_id": { "description": "Unique identifier for the balance transaction, prefixed with `fbtxn_`.", "type": "string", "example": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "amount": { "description": "Gross amount of the transaction, in the smallest currency unit (e.g., `1000` = $10.00 USD). Positive for funds added to your balance (e.g., charges) and negative for funds removed (e.g., refunds, payouts, dispute debits).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "available_on": { "description": "When the funds become available in your bank account. RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "created_at": { "description": "When the transaction was created. RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" }, "exchange_rate": { "description": "The exchange rate applied if the transaction involved a currency conversion. `null` when no conversion took place.", "type": [ "number", "null" ], "format": "double", "example": 1.0 }, "fee": { "description": "Total processing fee deducted from `amount`, in the smallest currency unit (e.g., `30` = $0.30 USD). `0` when no fee applies.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "net": { "description": "Net amount that affects your balance after `fee` is applied (`net = amount - fee`), in the smallest currency unit (e.g., `970` = $9.70 USD).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "reporting_category": { "description": "High-level accounting category for the transaction. `null` if not yet categorized.", "type": [ "string", "null" ], "example": "example_value" }, "checkout_session_id": { "description": "ID of the Checkout Session that originated this transaction, if it stems from a checkout.", "type": [ "string", "null" ], "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "client_reference_id": { "description": "Your own identifier for the originating object, carried over from the checkout session or payment.", "type": [ "string", "null" ], "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "status": { "description": "Availability status of the funds: `pending` (not yet available) or `available` (settled and withdrawable).", "$ref": "#/components/schemas/BalanceTransactionStatus" }, "source_id": { "description": "ID of the Flex object that produced this transaction (e.g., a Charge `fch_`, Refund `fre_`, or Payout `fpo_`). `null` if the source has not been resolved to a Flex object.", "type": [ "string", "null" ], "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "type": { "description": "The type of transaction.", "type": [ "string", "null" ] }, "flex_payment_intent_id": { "description": "ID of the Payment Intent associated with this transaction, if any. `null` for transactions not tied to a payment (e.g., payouts).", "type": [ "string", "null" ], "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "test_mode": { "description": "Whether this transaction was created in test mode. `true` for test-mode data, `false` for live data.", "type": "boolean", "example": false }, "mid": { "description": "Merchant identifier (MID) for the account that processed the transaction.", "type": [ "string", "null" ], "example": "example_value" }, "currency": { "description": "Three-letter ISO currency code, in lowercase (e.g., `usd`).", "type": [ "string", "null" ], "example": "usd" }, "metadata": { "description": "Set of key-value pairs you can attach to the object for storing additional structured information.", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": { "order_id": "8842", "channel": "shopify" } }, "transaction_fee_amount": { "description": "Portion of `fee` attributable to standard transaction processing, in the smallest currency unit. `null` if not broken out.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "interchange_fee_amount": { "description": "Portion of `fee` attributable to card-network interchange, in the smallest currency unit. `null` if not broken out.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "lmn_fee_amount": { "description": "Portion of `fee` attributable to Letter of Medical Necessity (LMN) processing, in the smallest currency unit. `null` if not applicable.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "dispute_fee_amount": { "description": "Portion of `fee` attributable to a dispute, in the smallest currency unit. `null` if not applicable.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "card_type": { "description": "Card funding type used for the transaction.", "type": [ "string", "null" ] }, "card_network": { "description": "Card network used for the transaction (e.g., `visa`, `mastercard`).", "type": [ "string", "null" ] } }, "example": { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "available_on": "string", "created_at": "2026-06-15T14:30:00Z", "exchange_rate": 1.0, "fee": 2500, "net": 2500, "reporting_category": "example_value", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "available", "source_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "string", "flex_payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "mid": "example_value", "currency": "usd", "metadata": { "order_id": "8842", "channel": "shopify" }, "transaction_fee_amount": 0, "interchange_fee_amount": 0, "lmn_fee_amount": 0, "dispute_fee_amount": 0, "card_type": "string", "card_network": "string" } }, "ChargeStatus": { "description": "The outcome of the charge.", "type": "string", "enum": [ "succeeded", "pending", "failed" ], "example": "succeeded" }, "ThreeDSecureOutcome": { "description": "3D Secure authentication outcome for the charge.", "type": "object", "properties": { "authentication_flow": { "description": "How the customer was authenticated: `challenge` or `frictionless`.", "type": [ "string", "null" ] }, "result": { "description": "Outcome of 3D Secure authentication.", "type": [ "string", "null" ] }, "result_reason": { "description": "Additional detail about why 3DS succeeded or failed.", "type": [ "string", "null" ] }, "version": { "description": "The version of 3D Secure used.", "type": [ "string", "null" ] } }, "example": { "authentication_flow": "string", "result": "string", "result_reason": "string", "version": "string" } }, "DeclineDetails": { "description": "Decline and risk details captured at the time of a failed or blocked charge.\n\nAbsent for successful, non-declined charges.", "type": "object", "properties": { "failure_code": { "description": "Error code for the charge failure (e.g. `card_declined`, `expired_card`).", "type": [ "string", "null" ] }, "decline_code": { "description": "More specific decline reason (e.g. `insufficient_funds`, `lost_card`).", "type": [ "string", "null" ] }, "failure_message": { "description": "User-facing failure message.", "type": [ "string", "null" ] }, "outcome_type": { "description": "The outcome type of the decline.", "type": [ "string", "null" ] }, "network_status": { "description": "Network-level status: `approved_by_network`, `declined_by_network`, etc.", "type": [ "string", "null" ] }, "seller_message": { "description": "Technical explanation of the outcome for the merchant.", "type": [ "string", "null" ] }, "reason": { "description": "Fraud/risk reason (e.g. `elevated_risk_level`).", "type": [ "string", "null" ] }, "risk_level": { "description": "The risk level assessed for the payment.", "type": [ "string", "null" ] } }, "example": { "failure_code": "string", "decline_code": "string", "failure_message": "string", "outcome_type": "string", "network_status": "string", "seller_message": "string", "reason": "string", "risk_level": "string" } }, "PaymentCardType": { "type": "string", "enum": [ "primary", "secondary" ], "x-ms-enum": { "name": "PaymentCardType", "modelAsString": false, "values": [ { "value": "primary", "name": "Primary", "description": "In a split cart, `Primary` refers to the HSA/FSA eligible card. In a single cart (whether it's HSA/FSA or a fully ineligible cart), `Primary` refers to the only payment card used." }, { "value": "secondary", "name": "Secondary", "description": "In a split cart and partial authorization payment, `Secondary` refers to the non-eligible or backup credit card used for ineligible items." } ] }, "description": "- `primary`: In a split cart, `Primary` refers to the HSA/FSA eligible card. In a single cart (whether it's HSA/FSA or a fully ineligible cart), `Primary` refers to the only payment card used.\n- `secondary`: In a split cart and partial authorization payment, `Secondary` refers to the non-eligible or backup credit card used for ineligible items.", "example": "primary" }, "LastPaymentError": { "description": "Structured error details from the most recent failed payment attempt on a payment intent.", "type": "object", "required": [ "type" ], "properties": { "type": { "description": "The type of error (card, invalid_request, api, etc.)", "type": "string" }, "code": { "description": "Machine-readable error code (card_declined, expired_card, etc.)", "type": [ "string", "null" ] }, "decline_code": { "description": "Card-specific decline code (insufficient_funds, lost_card, etc.)", "type": [ "string", "null" ] }, "message": { "description": "Human-readable error description.", "type": [ "string", "null" ] }, "payment_method": { "description": "The Flex payment method ID that failed.", "type": [ "string", "null" ], "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "example": { "type": "string", "code": "string", "decline_code": "string", "message": "string", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "ShippingRateOptions": { "description": "A resolved shipping option attached to a checkout session or payment link, capturing the applied shipping rate and its cost.", "type": "object", "required": [ "shipping_amount", "shipping_rate_id" ], "properties": { "shipping_rate_id": { "description": "ID of the applied shipping rate.", "type": "string", "example": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "shipping_amount": { "description": "The shipping cost, in the smallest currency unit (e.g., `500` = $5.00 USD). Charged in USD.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "display_name": { "description": "The display name of the shipping rate (e.g., \"Standard Shipping\", \"Express\").", "type": [ "string", "null" ], "example": "Example" } }, "example": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" } }, "Expandable_for_SplitCart": { "anyOf": [ { "type": "string", "example": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/SplitCart" } ], "description": "An expandable field — either a string ID or an expanded SplitCart object.", "example": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "SplitCart": { "description": "A SplitCart represents a checkout session whose items are divided into two separate payments: one for HSA/FSA-eligible items and one for non-eligible items. It is created automatically when a session mixes eligible and ineligible products, so the customer can pay for the eligible portion with their HSA/FSA card.", "type": "object", "required": [ "eligible_cart", "non_eligible_cart", "split_cart_id" ], "properties": { "split_cart_id": { "description": "Unique identifier for the split cart.", "type": "string", "example": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "eligible_cart": { "description": "The portion of the cart containing HSA/FSA-eligible items, charged to the customer's HSA/FSA payment method.", "$ref": "#/components/schemas/Cart" }, "non_eligible_cart": { "description": "The portion of the cart containing non-eligible items, charged to the customer's standard payment method.", "$ref": "#/components/schemas/Cart" }, "checkout_session_id": { "description": "ID of the Checkout Session this split cart belongs to. `null` until the split cart has been associated with a session.", "type": [ "string", "null" ], "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "example": { "split_cart_id": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "eligible_cart": { "amount_total": 2500, "amount_subtotal": 2500, "amount_tax": 2500, "amount_discount": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount_shipping": 2500 }, "non_eligible_cart": { "amount_total": 2500, "amount_subtotal": 2500, "amount_tax": 2500, "amount_discount": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount_shipping": 2500 }, "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "Cart": { "description": "One half of a SplitCart: the totals and payment intent for either the HSA/FSA-eligible or the non-eligible items in a split checkout.", "type": "object", "required": [ "amount_discount", "amount_subtotal", "amount_tax", "amount_total" ], "properties": { "amount_total": { "description": "Total amount for this cart after tax, shipping, and discounts, in the smallest currency unit (e.g., `2500` = $25.00 USD).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_subtotal": { "description": "Sum of the line item amounts before tax, shipping, and discounts, in the smallest currency unit (e.g., `2000` = $20.00 USD).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_tax": { "description": "Total tax applied to this cart, in the smallest currency unit (e.g., `150` = $1.50 USD).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_discount": { "description": "Total discount applied to this cart, in the smallest currency unit (e.g., `500` = $5.00 USD).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "payment_intent": { "description": "The PaymentIntent that collects payment for this cart. `null` until a payment intent has been created for it. Expandable when `split_cart` is expanded with `payment_intent`.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_PaymentIntent" }, { "type": "null" } ] }, "amount_shipping": { "description": "Total shipping charged to this cart, in the smallest currency unit (e.g., `599` = $5.99 USD). `null` when no shipping applies.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 } }, "example": { "amount_total": 2500, "amount_subtotal": 2500, "amount_tax": 2500, "amount_discount": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount_shipping": 2500 } }, "Status": { "description": "The status of the checkout session.", "type": "string", "enum": [ "open", "paid", "complete", "canceled", "expired" ], "example": "open" }, "V1Fee": { "description": "A simplified representation of a fee for API responses", "type": "object", "required": [ "amount", "fee_id", "fee_type" ], "properties": { "fee_id": { "description": "Unique identifier for the fee.", "type": "string", "example": "ffee_1234567890" }, "amount": { "description": "The configured gross amount of the fee in cents. The payable fee total after fee-scoped coupons is reported in the checkout session's `total_details.amount_fee`.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "name": { "description": "The name of the fee.", "type": [ "string", "null" ], "example": "Example" }, "description": { "description": "The description of the fee.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" }, "fee_type": { "description": "The type of the fee.", "$ref": "#/components/schemas/FeeType" }, "applied": { "description": "Whether the fee was applied to the checkout session.", "type": [ "boolean", "null" ] }, "waived_reason": { "description": "Why the fee was waived. `null` means no waiver reason is recorded: the fee is still applied, was never applied in the first place (e.g. the cart has no payable LOMN items), or was waived before this field shipped (2026-08). Render a \"waived\" row only when `applied == false` AND this is non-null — `applied == false` alone also covers never-applied fees.", "anyOf": [ { "$ref": "#/components/schemas/FeeWaivedReason" }, { "type": "null" } ] } }, "example": { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } }, "FeeWaivedReason": { "description": "Why a fee was waived. `existing_letter`: the customer already has a qualifying letter — an existing validated condition, a completed consultation, or a letter carried over from another partner in the same organization. `disqualified`: the customer was disqualified from the LOMN consultation (no conditions apply), so the consultation fee cannot be charged. Absent (JSON `null`) means no waiver was recorded — see the field's own description for what that implies.", "type": "string", "enum": [ "existing_letter", "disqualified" ], "example": "existing_letter" }, "CustomText": { "description": "Custom text displayed to customers in checkout UI", "type": "object", "properties": { "after_submit": { "description": "Text shown after payment submission", "anyOf": [ { "$ref": "#/components/schemas/CustomTextMessage" }, { "type": "null" } ] }, "shipping_address": { "description": "Text shown in shipping address collection", "anyOf": [ { "$ref": "#/components/schemas/CustomTextMessage" }, { "type": "null" } ] }, "submit": { "description": "Text shown near submit button", "anyOf": [ { "$ref": "#/components/schemas/CustomTextMessage" }, { "type": "null" } ] }, "terms_of_service_acceptance": { "description": "Text shown for terms of service acceptance", "anyOf": [ { "$ref": "#/components/schemas/CustomTextMessage" }, { "type": "null" } ] }, "terms_of_service_checkbox_required": { "description": "Whether the terms of service acceptance checkbox must be shown and checked", "type": [ "boolean", "null" ] }, "payment": { "description": "Text shown in payment section", "anyOf": [ { "$ref": "#/components/schemas/CustomTextMessage" }, { "type": "null" } ] } }, "example": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } } }, "CustomTextMessage": { "description": "Individual message field matching Stripe's structure", "type": "object", "required": [ "message" ], "properties": { "message": { "description": "The actual text message (plain text only, 1-1200 characters)", "type": "string", "maxLength": 1200, "minLength": 1, "example": "Premium SPF 50 mineral sunscreen" } }, "example": { "message": "Premium SPF 50 mineral sunscreen" } }, "V1SubscriptionData": { "description": "Subscription Data holds the trial and cancellation settings to apply to the subscription that a checkout session creates once payment completes.", "type": "object", "properties": { "cancel_at": { "description": "A future RFC 3339 timestamp at which the created subscription will automatically be canceled. `null` if no future cancellation is scheduled.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" }, "trial_end": { "description": "RFC 3339 timestamp at which the trial period ends for the created subscription. `null` if no trial end was set on the checkout session.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "cancel_at_period_end": { "description": "Whether the created subscription will cancel at the end of its current billing period rather than renewing.", "type": [ "boolean", "null" ], "example": false }, "trial_period_days": { "description": "Length of the trial period, in days, for the created subscription. `null` if no day-based trial was set on the checkout session.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "trial_settings": { "description": "Settings that control what Stripe does when the trial ends. `null` preserves Stripe's existing behavior.", "anyOf": [ { "$ref": "#/components/schemas/SubscriptionTrialSettings" }, { "type": "null" } ] }, "backup_payment_method": { "description": "The backup payment method setting this session was created with. `null` if it set none. Ignores the partner default and whether the feature is enabled; the payments page's top-level `backup_payment_method` is what checkout acts on.", "anyOf": [ { "$ref": "#/components/schemas/BackupPaymentMethodRequirement" }, { "type": "null" } ] } }, "example": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } } }, "SubscriptionTrialSettings": { "description": "Settings that control the end of a subscription trial.", "type": "object", "required": [ "end_behavior" ], "properties": { "end_behavior": { "$ref": "#/components/schemas/SubscriptionTrialEndBehavior" } }, "example": { "end_behavior": { "missing_payment_method": "cancel" } } }, "SubscriptionTrialEndBehavior": { "description": "Behavior to apply when a trial ends.", "type": "object", "required": [ "missing_payment_method" ], "properties": { "missing_payment_method": { "description": "What Stripe should do when the trial ends without a payment method.", "$ref": "#/components/schemas/MissingPaymentMethodBehavior" } }, "example": { "missing_payment_method": "cancel" } }, "MissingPaymentMethodBehavior": { "type": "string", "enum": [ "cancel" ], "x-ms-enum": { "name": "MissingPaymentMethodBehavior", "modelAsString": false, "values": [ { "value": "cancel", "name": "Cancel", "description": "Cancel the subscription when the trial ends." } ] }, "description": "Supported behavior when a trial ends without a payment method.\n\n- `cancel`: Cancel the subscription when the trial ends.", "example": "cancel" }, "BackupPaymentMethodRequirement": { "type": "string", "enum": [ "required", "optional" ], "x-ms-enum": { "name": "BackupPaymentMethodRequirement", "modelAsString": false, "values": [ { "value": "required", "name": "Required", "description": "Checkout cannot complete without a backup card." }, { "value": "optional", "name": "Optional", "description": "Checkout offers a backup card the shopper may skip. A card they enter that fails is reported, not dropped." } ] }, "description": "Whether a subscription checkout must collect a backup payment method, or merely offers one.\n\n- `required`: Checkout cannot complete without a backup card.\n- `optional`: Checkout offers a backup card the shopper may skip. A card they enter that fails is reported, not dropped.", "example": "required" }, "TaxRate": { "description": "A fixed tax amount to apply to a Checkout Session or line item. Use this to pass a tax figure you have calculated yourself, rather than having Flex compute it.", "type": "object", "required": [ "amount" ], "properties": { "amount": { "description": "The tax amount to apply, in the smallest currency unit (e.g., `175` = $1.75 USD).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 } }, "example": { "amount": 2500 } }, "TaxCalculationMode": { "description": "Whether tax should be calculated exclusive or inclusive of the provided total", "type": "string", "enum": [ "exclusive", "inclusive" ], "example": "exclusive" }, "TotalDetails": { "description": "Tax and discount details for the computed total amount.", "type": "object", "properties": { "amount_discount": { "description": "Sum of discounts recorded on line items, plus any unscoped subscription discount allocated to fees. Fee-scoped coupon reductions are reflected in `amount_fee` instead of being duplicated here.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_tax": { "description": "This is the sum of all the tax amounts.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_shipping": { "description": "This is the sum of all the shipping amounts.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_iias": { "description": "This is the sum of all the iias line items.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_vision": { "description": "Sum of the line item amounts classified as vision care, in the smallest currency unit (e.g., `2500` = $25.00 USD). `null` when no vision items are present.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_prescription": { "description": "Sum of the line item amounts classified as prescription, in the smallest currency unit (e.g., `3000` = $30.00 USD). `null` when no prescription items are present.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_service": { "description": "Sum of the line item amounts classified as a medical service, in the smallest currency unit (e.g., `5000` = $50.00 USD). `null` when no service items are present.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_fee": { "description": "The fee contribution after fee-scoped coupons and before any unscoped subscription discount reported in `amount_discount`.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "breakdown": { "description": "Breakdown of the components that make up the total details.", "anyOf": [ { "$ref": "#/components/schemas/Breakdown" }, { "type": "null" } ] } }, "example": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } } }, "Breakdown": { "description": "Breakdown of the components that make up the total details.\n\nMatches Stripe's structure. See OpenAPI spec: https://github.com/stripe/openapi - schemas: payment_pages_checkout_session_total_details_resource_breakdown", "type": "object", "properties": { "discounts": { "description": "The aggregated discounts.", "type": "array", "items": { "$ref": "#/components/schemas/DiscountAmount" } } }, "example": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "DiscountAmount": { "description": "A discount applied to the checkout session.\n\nMatches Stripe's `line_items_discount_amount` schema.", "type": "object", "required": [ "discount" ], "properties": { "discount": { "description": "The discount that was applied.", "$ref": "#/components/schemas/Discount" } }, "example": { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } }, "FutureUse": { "type": "string", "enum": [ "on_session", "off_session" ], "x-ms-enum": { "name": "FutureUse", "modelAsString": false, "values": [ { "value": "on_session", "name": "OnSession", "description": "Standard payments requiring customer auth" }, { "value": "off_session", "name": "OffSession", "description": "Allows payments without the customer present in the flow" } ] }, "description": "- `on_session`: Standard payments requiring customer auth\n- `off_session`: Allows payments without the customer present in the flow", "example": "on_session" }, "PaymentMethodOptions": { "description": "Payment method-specific options applied to a Checkout Session.", "type": "object", "properties": { "card": { "description": "Options that apply to card payments. `null` when no card-specific options are set.", "anyOf": [ { "$ref": "#/components/schemas/CardPaymentMethodOptions" }, { "type": "null" } ] } }, "example": { "card": { "request_three_d_secure": "automatic" } } }, "CardPaymentMethodOptions": { "description": "Card-specific payment options for a Checkout Session.", "type": "object", "required": [ "request_three_d_secure" ], "properties": { "request_three_d_secure": { "description": "Whether 3D Secure authentication is requested for card payments. One of `automatic` (Default; request only when required), `any` (request whenever supported), or `challenge` (request a customer challenge).", "$ref": "#/components/schemas/RequestThreeDSecure" } }, "example": { "request_three_d_secure": "automatic" } }, "RequestThreeDSecure": { "description": "Whether to request 3D Secure authentication on card payments.", "type": "string", "enum": [ "automatic", "any", "challenge" ], "example": "automatic" }, "NextAction": { "description": "Represents an action required to complete the checkout. The `type` field indicates which action is needed, and the corresponding nested object contains the action-specific data.", "type": "object", "properties": { "type": { "type": "string", "enum": [ "collect_letter_of_medical_necessity", "payment_failed", "provide_second_payment_method", "provide_alternative_payment_method" ] }, "collect_letter_of_medical_necessity": { "$ref": "#/components/schemas/CollectLetterOfMedicalNecessityAction", "description": "Redirect the customer to collect a Letter of Medical Necessity" }, "payment_failed": { "$ref": "#/components/schemas/PaymentFailedAction", "description": "Payment failed during off-session checkout (e.g., card declined, insufficient funds)" }, "provide_second_payment_method": { "$ref": "#/components/schemas/ProvideSecondPaymentMethodAction", "description": "A second payment method is required for a split cart off-session checkout" }, "provide_alternative_payment_method": { "$ref": "#/components/schemas/ProvideAlternativePaymentMethodAction", "description": "An alternative payment method is required because the provided payment method cannot be used to complete the transaction." } }, "required": [ "type" ], "example": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } } }, "CollectLetterOfMedicalNecessityAction": { "description": "Data for the collect_letter_of_medical_necessity next action.", "type": "object", "required": [ "url" ], "properties": { "url": { "description": "The URL where the customer should be redirected to provide the letter.", "type": "string", "example": "https://example.com" } }, "example": { "url": "https://example.com" } }, "PaymentFailedAction": { "description": "Data for the payment_failed next action.", "type": "object", "required": [ "message", "url" ], "properties": { "message": { "description": "A human-readable message describing the payment failure.", "type": "string", "example": "Premium SPF 50 mineral sunscreen" }, "url": { "description": "The URL where the customer should be redirected to retry payment.", "type": "string", "example": "https://example.com" }, "decline_code": { "description": "The decline code from the payment processor, if available.", "type": [ "string", "null" ] }, "error_code": { "description": "The error code from the payment processor, if available.", "type": [ "string", "null" ] } }, "example": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" } }, "ProvideSecondPaymentMethodAction": { "description": "Data for the provide_second_payment_method next action.", "type": "object", "required": [ "eligible_amount", "ineligible_amount", "message", "url" ], "properties": { "message": { "description": "A human-readable message explaining that a second payment method is needed.", "type": "string", "example": "Premium SPF 50 mineral sunscreen" }, "url": { "description": "The URL where the customer should be redirected to provide both payment methods.", "type": "string", "example": "https://example.com" }, "eligible_amount": { "description": "The amount in cents for HSA/FSA-eligible items.", "type": "integer", "format": "int32", "minimum": -2147483648.0, "maximum": 2147483647.0 }, "ineligible_amount": { "description": "The amount in cents for non-eligible items.", "type": "integer", "format": "int32", "minimum": -2147483648.0, "maximum": 2147483647.0 } }, "example": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 } }, "ProvideAlternativePaymentMethodAction": { "description": "Data for the provide_alternative_payment_method next action.", "type": "object", "required": [ "message", "url" ], "properties": { "message": { "description": "A human-readable message explaining why an alternative payment method is needed.", "type": "string", "example": "Premium SPF 50 mineral sunscreen" }, "url": { "description": "The URL where the customer should be redirected to provide a different payment method.", "type": "string", "example": "https://example.com" } }, "example": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "SellingPlan": { "description": "A Shopify selling plan a Checkout Session's originating order was placed under. Two sessions sharing a plan for one customer are renewals of the same subscription.", "type": "object", "required": [ "id", "name" ], "properties": { "id": { "description": "The selling plan's Shopify global ID, e.g. `gid://shopify/SellingPlan/693250982253`.", "type": "string" }, "name": { "description": "The merchant-authored display name, e.g. `Subscribe & save`. Display only — the merchant can rename a plan at any time, so never group on this.", "type": "string" }, "billing_interval": { "description": "How often the plan bills, as Shopify reported it when the order was recorded. Omitted when Shopify reported no recurring cadence, e.g. for a plan billed once up front.", "anyOf": [ { "$ref": "#/components/schemas/SellingPlanBillingInterval" }, { "type": "null" } ] } }, "example": { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } }, "SellingPlanBillingInterval": { "description": "A selling plan's billing cadence: every `interval_count` `interval`s.", "type": "object", "required": [ "interval", "interval_count" ], "properties": { "interval": { "description": "The unit the cadence counts in.", "$ref": "#/components/schemas/RecurringInterval" }, "interval_count": { "description": "The number of intervals between bills, e.g. `2` for every two months.", "type": "integer", "format": "int64", "minimum": -9007199254740991.0, "maximum": 9007199254740991.0 } }, "example": { "interval": "day", "interval_count": 0 } }, "ShopifyPaymentDetails": { "description": "How a Shopify order was paid: its latest successful sale or capture.", "type": "object", "required": [ "gateway" ], "properties": { "gateway": { "description": "The Shopify payment gateway, e.g. `shopify_payments` or `paypal`.", "type": "string" }, "wallet": { "description": "The digital wallet the card was presented through, e.g. `apple_pay` or `shopify_pay`.", "type": [ "string", "null" ] }, "card": { "description": "The card, when the order was paid by one. Absent for PayPal.", "anyOf": [ { "$ref": "#/components/schemas/ShopifyPaymentCard" }, { "type": "null" } ] } }, "example": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } } }, "ShopifyPaymentCard": { "description": "The card on a Shopify order payment.", "type": "object", "required": [ "brand", "last4" ], "properties": { "brand": { "$ref": "#/components/schemas/CardBrand" }, "last4": { "description": "The last four digits of the card number.", "type": "string", "example": "4242" } }, "example": { "brand": "american_express", "last4": "4242" } }, "Expandable_for_PartnerMetadata": { "anyOf": [ { "type": "string", "example": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/PartnerMetadata" } ], "description": "An expandable field — either a string ID or an expanded PartnerMetadata object.", "example": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "PartnerMetadata": { "description": "The public summary of your account, exposed as the expandable `partner` object embedded on other Flex objects such as checkout sessions, subscriptions, and receipts.", "type": "object", "required": [ "name", "partner_id", "website_url" ], "properties": { "partner_id": { "description": "Unique identifier of the account, prefixed with `facct_`.", "type": "string", "example": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "name": { "description": "Your display name, as shown to customers during checkout.", "type": "string", "example": "Example" }, "website_url": { "description": "Your public website URL.", "type": "string" }, "description": { "description": "A short description of your business.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" } }, "example": { "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "Example", "website_url": "string", "description": "Premium SPF 50 mineral sunscreen" } }, "PlatformFees": { "description": "Platform fees charged on a checkout session. Present only when you are on the deferred-collection feature and the checkout has completed.", "type": "object", "required": [ "letter_fee" ], "properties": { "letter_fee": { "description": "The Letter of Medical Necessity fee charged on this checkout.", "$ref": "#/components/schemas/LetterFee" } }, "example": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } }, "LetterFee": { "description": "Letter-fee details surfaced on the checkout session response.", "type": "object", "required": [ "amount", "status" ], "properties": { "amount": { "description": "Amount charged for the letter, in cents. `0` when waived (disqualified, pre-existing, OTP-verified, existing consultation, etc.).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "type": { "description": "Billing classification. Only present when `amount > 0`. - `\"new\"` — any new consultation in the checkout (takes precedence when mixed with expired). - `\"expired\"` — only expired consultation(s) are being re-billed.", "type": [ "string", "null" ] }, "status": { "description": "Collection state of the letter fee.", "$ref": "#/components/schemas/LetterFeeStatus" } }, "example": { "amount": 2500, "type": "string", "status": "pending" } }, "LetterFeeStatus": { "type": "string", "enum": [ "pending", "waived", "collected", "deferred", "settled" ], "x-ms-enum": { "name": "LetterFeeStatus", "modelAsString": false, "values": [ { "value": "pending", "name": "Pending", "description": "Fee determined but not yet collected — transient in-flight state." }, { "value": "waived", "name": "Waived", "description": "No fee applies (disqualified, pre-existing, OTP-verified, etc.). Always paired with `letter_fee_amount = 0` and `billing_type = NULL`." }, { "value": "collected", "name": "Collected", "description": "Fee captured as part of the checkout transaction." }, { "value": "deferred", "name": "Deferred", "description": "Fee deferred to end-of-month batch settlement." }, { "value": "settled", "name": "Settled", "description": "Deferred fee charged via the monthly batch." } ] }, "description": "Lifecycle state of a [`CheckoutSessionLetterFee`] row.\n\nStored as a lowercase string in the `status` TEXT column (matches the DB default `'pending'` set by migration `20260416001655`).\n\n- `pending`: Fee determined but not yet collected — transient in-flight state.\n- `waived`: No fee applies (disqualified, pre-existing, OTP-verified, etc.). Always paired with `letter_fee_amount = 0` and `billing_type = NULL`.\n- `collected`: Fee captured as part of the checkout transaction.\n- `deferred`: Fee deferred to end-of-month batch settlement.\n- `settled`: Deferred fee charged via the monthly batch.", "example": "pending" }, "SetupIntent": { "description": "A SetupIntent represents your intent to set up a customer's payment method for future payments, without charging it immediately. Use it to collect and verify payment method details that can later be used off-session (for example, to bill a subscription or invoice).", "type": "object", "required": [ "created_at", "partner_id", "setup_intent_id", "status", "test_mode", "usage" ], "properties": { "setup_intent_id": { "description": "The unique identifier for the object.", "type": "string", "example": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "client_secret": { "description": "The client secret used to confirm this SetupIntent from your frontend. Present when the SetupIntent is retrieved or created; `null` when it appears in a list response. Treat it as sensitive: do not log or store it, and expose it only to the customer over TLS.", "type": [ "string", "null" ] }, "customer": { "description": "The Customer this SetupIntent belongs to; returned as the ID by default and expandable to the full object.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_Customer" }, { "type": "null" } ] }, "description": { "description": "An arbitrary string attached to the setup intent.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" }, "payment_method": { "description": "Payment method used with this SetupIntent.", "type": [ "string", "null" ], "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "partner_id": { "description": "The ID of the account this SetupIntent belongs to.", "type": "string", "example": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "metadata": { "description": "Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.", "type": [ "object", "null" ], "additionalProperties": { "type": "object" }, "example": { "order_id": "8842", "channel": "shopify" } }, "created_at": { "description": "Time at which the object was created. ISO 8601 format.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "test_mode": { "description": "Whether or not the setup intent is in test mode.", "type": "boolean", "example": false }, "status": { "description": "The current status of the setup intent.", "$ref": "#/components/schemas/Status2" }, "usage": { "description": "Indicates how the payment method is intended to be used in the future.", "$ref": "#/components/schemas/Usage" }, "subscription_id": { "description": "The ID of the Subscription this SetupIntent is associated with (for payment method updates).", "type": [ "string", "null" ], "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "example": { "setup_intent_id": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_secret": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "status": "requires_payment_method", "usage": "off_session", "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "Status2": { "description": "The status of the setup intent.", "type": "string", "enum": [ "requires_payment_method", "requires_confirmation", "requires_action", "processing", "succeeded", "canceled" ], "example": "requires_payment_method" }, "Usage": { "description": "Whether the saved payment method is intended for off-session or on-session future payments.", "type": "string", "enum": [ "off_session", "on_session" ], "example": "off_session" }, "EarlyFraudWarning": { "description": "An EarlyFraudWarning is a signal from the card issuer that a charge is likely to be disputed as fraudulent. Acting on it — for example by refunding the charge — can help you avoid a dispute and its fee.", "type": "object", "required": [ "actionable", "created_at", "early_fraud_warning_id", "fraud_type", "partner_id", "test_mode" ], "properties": { "early_fraud_warning_id": { "description": "Unique identifier for the early fraud warning, prefixed with `fefw_`.", "type": "string", "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "charge_id": { "description": "ID of the Charge this early fraud warning is associated with. `null` if the charge could not be resolved.", "type": [ "string", "null" ], "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "payment_intent_id": { "description": "ID of the PaymentIntent this early fraud warning is associated with. `null` if it could not be resolved.", "type": [ "string", "null" ], "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "actionable": { "description": "Whether the card issuer expects the charge to be disputed. When `true`, the charge is likely to become a dispute, and proactively refunding it can help avoid a dispute and its fee.", "type": "boolean", "example": false }, "fraud_type": { "description": "The type of fraud reported by the card issuer.", "$ref": "#/components/schemas/FraudType" }, "partner_id": { "description": "ID of the account that owns this early fraud warning.", "type": "string", "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "test_mode": { "description": "Whether the early fraud warning was created in test mode. `true` for warnings created with test API keys.", "type": "boolean", "example": false }, "client_reference_id": { "description": "Your own identifier for the customer or payment this warning relates to, copied from the originating payment.", "type": [ "string", "null" ], "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "created_at": { "description": "Time at which the early fraud warning was created, as an RFC 3339 date-time string.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" } }, "example": { "early_fraud_warning_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "actionable": false, "fraud_type": "card_never_received", "partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z" } }, "FraudType": { "description": "The type of fraud labelled by the card issuer.", "type": "string", "enum": [ "card_never_received", "fraudulent_card_application", "made_with_counterfeit_card", "made_with_lost_card", "made_with_stolen_card", "misc", "unauthorized_use_of_card" ], "example": "card_never_received" }, "Review": { "description": "A Review represents a payment flagged by fraud detection for manual review. A review stays open while the payment awaits a decision and closes once it is approved or otherwise resolved.", "type": "object", "required": [ "created_at", "open", "opened_reason", "partner_id", "reason", "review_id", "test_mode" ], "properties": { "review_id": { "description": "Unique identifier for the review, prefixed with `frv_`.", "type": "string", "example": "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "charge_id": { "description": "ID of the Charge under review, prefixed with `fch_`. `null` if the review is not associated with a specific charge.", "type": [ "string", "null" ], "example": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "payment_intent_id": { "description": "ID of the Payment Intent under review, prefixed with `fpi_`. `null` if the review is not associated with a specific payment intent.", "type": [ "string", "null" ], "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "partner_id": { "description": "ID of the account that owns the payment under review, prefixed with `facct_`.", "type": "string", "example": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "reason": { "description": "The current reason associated with the review. Reflects why the review is open while `open` is `true`, and the outcome once it is closed.", "$ref": "#/components/schemas/ReviewReason" }, "opened_reason": { "description": "Reason the review was originally opened: `rule` (triggered by an automated fraud rule) or `manual` (opened by hand).", "$ref": "#/components/schemas/ReviewOpenedReason" }, "closed_reason": { "description": "The reason the review was closed. Omitted while the review is still open.", "anyOf": [ { "$ref": "#/components/schemas/ReviewClosedReason" }, { "type": "null" } ] }, "open": { "description": "Whether the review is still open. `true` while the payment is under review, `false` once it has been resolved.", "type": "boolean", "example": false }, "billing_zip": { "description": "Billing ZIP/postal code provided for the payment under review. Omitted if not available.", "type": [ "string", "null" ] }, "ip_address": { "description": "IP address from which the payment under review was made. Omitted if not available.", "type": [ "string", "null" ] }, "test_mode": { "description": "Whether this review was created in test mode. `true` for test-mode data, `false` for live data.", "type": "boolean", "example": false }, "client_reference_id": { "description": "Your own identifier for the payment under review, carried over from the originating checkout session or payment. Omitted if none was set.", "type": [ "string", "null" ], "example": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "created_at": { "description": "When the review was created (ISO 8601 format).", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" } }, "example": { "review_id": "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reason": "rule", "opened_reason": "rule", "closed_reason": "approved", "open": false, "billing_zip": "string", "ip_address": "string", "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z" } }, "ReviewReason": { "description": "Why the review is currently open or closed.", "type": "string", "enum": [ "rule", "manual", "approved", "refunded", "refunded_as_fraud", "disputed", "redacted" ], "example": "rule" }, "ReviewOpenedReason": { "description": "Why the review was opened.", "type": "string", "enum": [ "rule", "manual" ], "example": "rule" }, "ReviewClosedReason": { "description": "Why the review was closed.", "type": "string", "enum": [ "approved", "disputed", "redacted", "refunded", "refunded_as_fraud" ], "example": "approved" }, "Export": { "description": "An Export represents an asynchronous request to generate a CSV file of your data, such as payments, subscriptions, customers, or reconciliation records. Create one to start the job, poll it until its `status` is `completed`, then request a presigned URL to download the file.", "type": "object", "required": [ "created_at", "export_id", "status", "test_mode", "type" ], "properties": { "export_id": { "description": "Unique identifier for the export.", "type": "string", "example": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "description": { "description": "An arbitrary description you can attach to the export for your own reference.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" }, "type": { "description": "The kind of data the export generates.", "$ref": "#/components/schemas/ExportType" }, "status": { "description": "The current state of the export job. The file is available to download only once the status is `completed`.", "$ref": "#/components/schemas/ExportStatus" }, "created_at": { "description": "Time at which the export was created, as an RFC 3339 timestamp.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "started_at": { "description": "Time at which the export job began processing, as an RFC 3339 timestamp. `null` until processing starts.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" }, "completed_at": { "description": "Time at which the export job finished, as an RFC 3339 timestamp. `null` until the export completes.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" }, "metadata": { "description": "Set of key-value pairs you can attach to the export for storing additional structured information.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "filters": { "description": "The criteria that restrict which records the export includes. `null` when no filter was supplied, in which case all records are exported.", "anyOf": [ { "$ref": "#/components/schemas/Filters" }, { "type": "null" } ] }, "test_mode": { "description": "Whether the export was created in test mode. `true` for test-mode exports, `false` for live-mode exports.", "type": "boolean", "example": false } }, "example": { "export_id": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "type": "product", "status": "created", "created_at": "2026-06-15T14:30:00Z", "started_at": "2026-06-15T14:30:00Z", "completed_at": "2026-06-15T14:30:00Z", "metadata": { "order_id": "8842", "channel": "shopify" }, "filters": { "payment": { "limit": 0, "status": "canceled", "starting_after": "string", "ending_before": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "limit": 0, "offset": 0, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string", "start_date": "string", "end_date": "string" }, "subscription": { "limit": 0, "offset": 0, "start_date": "string", "end_date": "string" }, "customer": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "product": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "charge_reconciliation": { "start_date": "string", "end_date": "string" }, "payout": { "start_date": "string", "end_date": "string" }, "dispute": { "start_date": "string", "end_date": "string" }, "line_item": { "start_date": "string", "end_date": "string" }, "line_item_revenue": { "start_date": "string", "end_date": "string" }, "balance_activity": { "start_date": "string", "end_date": "string" } }, "test_mode": false } }, "ExportType": { "description": "The type of records the export contains.", "type": "string", "enum": [ "product", "payment", "subscription", "customer", "checkout_session", "charge_reconciliation", "payout", "line_item", "line_item_revenue", "dispute", "balance_activity" ], "example": "product" }, "ExportStatus": { "description": "The processing status of the export.", "type": "string", "enum": [ "created", "started", "cancelled", "failed", "processing", "completed" ], "example": "created" }, "Filters": { "description": "Criteria that restrict which records an export includes. The filter variant must match the export's `type` (e.g. a `payment` export takes the `payment` filter); the unused criteria are ignored. When no filter is supplied, the export includes all of your records.", "type": "object", "properties": { "payment": { "type": "object", "properties": { "limit": { "description": "Accepted but not currently applied to the export.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "status": { "description": "Accepted but not currently applied to the export.", "anyOf": [ { "$ref": "#/components/schemas/PaymentIntentStatus" }, { "type": "null" } ] }, "starting_after": { "description": "Includes only payments created at or after this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "ending_before": { "description": "Includes only payments created at or before this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "customer": { "description": "Accepted but not currently applied to the export.", "type": [ "string", "null" ], "example": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "description": "Filters a `payment` export." }, "checkout_session": { "type": "object", "properties": { "limit": { "description": "Accepted but not currently applied to the export.", "type": [ "integer", "null" ], "format": "int64", "maximum": 9007199254740991.0, "minimum": -9007199254740991.0 }, "offset": { "description": "Accepted but not currently applied to the export.", "type": [ "integer", "null" ], "format": "int64", "maximum": 9007199254740991.0, "minimum": -9007199254740991.0 }, "payment_intent": { "description": "Accepted but not currently applied to the export.", "type": [ "string", "null" ], "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "client_reference_id": { "description": "Accepted but not currently applied to the export.", "type": [ "string", "null" ] }, "start_date": { "description": "Includes only checkout sessions created at or after this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "end_date": { "description": "Includes only checkout sessions created at or before this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] } }, "description": "Filters a `checkout_session` export." }, "subscription": { "type": "object", "properties": { "limit": { "description": "Accepted but not currently applied to the export.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "offset": { "description": "Accepted but not currently applied to the export.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "start_date": { "description": "Includes only subscriptions created at or after this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "end_date": { "description": "Includes only subscriptions created at or before this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] } }, "description": "Filters a `subscription` export." }, "customer": { "$ref": "#/components/schemas/PaginationFilter", "description": "Filters a `customer` export by creation date range." }, "product": { "$ref": "#/components/schemas/PaginationFilter", "description": "Filters a `product` export by creation date range." }, "charge_reconciliation": { "type": "object", "properties": { "start_date": { "description": "Includes only charges created at or after this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "end_date": { "description": "Includes only charges created at or before this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] } }, "description": "Filters a `charge_reconciliation` export." }, "payout": { "type": "object", "properties": { "start_date": { "description": "Includes only payouts created at or after this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "end_date": { "description": "Includes only payouts created at or before this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] } }, "description": "Filters a `payout` export." }, "dispute": { "type": "object", "properties": { "start_date": { "description": "Includes only disputes opened at or after this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "end_date": { "description": "Includes only disputes opened at or before this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] } }, "description": "Filters a `dispute` export by dispute (chargeback) open date." }, "line_item": { "type": "object", "properties": { "start_date": { "description": "Includes only line items created at or after this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "end_date": { "description": "Includes only line items created at or before this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] } }, "description": "Filters a `line_item` export." }, "line_item_revenue": { "type": "object", "properties": { "start_date": { "description": "Includes only line item revenue records created at or after this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "end_date": { "description": "Includes only line item revenue records created at or before this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] } }, "description": "Filters a `line_item_revenue` export." }, "balance_activity": { "type": "object", "properties": { "start_date": { "description": "Includes only balance transactions created at or after this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "end_date": { "description": "Includes only balance transactions created at or before this RFC 3339 timestamp.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] } }, "description": "Filters a `balance_activity` export by transaction date range (UTC). One row per balance transaction; the range may span any number of months." } }, "additionalProperties": false, "example": { "payment": { "limit": 0, "status": "canceled", "starting_after": "string", "ending_before": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "limit": 0, "offset": 0, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string", "start_date": "string", "end_date": "string" }, "subscription": { "limit": 0, "offset": 0, "start_date": "string", "end_date": "string" }, "customer": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "product": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "charge_reconciliation": { "start_date": "string", "end_date": "string" }, "payout": { "start_date": "string", "end_date": "string" }, "dispute": { "start_date": "string", "end_date": "string" }, "line_item": { "start_date": "string", "end_date": "string" }, "line_item_revenue": { "start_date": "string", "end_date": "string" }, "balance_activity": { "start_date": "string", "end_date": "string" } } }, "PaginationFilter": { "description": "Date-range bounds applied when generating customer and product exports.", "type": "object", "properties": { "limit": { "description": "Accepted but not currently applied; the export includes all records within the date range.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "offset": { "description": "Accepted but not currently applied; the export includes all records within the date range.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "starting_after": { "description": "Includes only records created at or after this RFC 3339 timestamp. When omitted, the export has no lower time bound.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] }, "ending_before": { "description": "Includes only records created at or before this RFC 3339 timestamp. When omitted, the export has no upper time bound.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] } }, "example": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" } }, "MultipleCheckoutSessionBody_for_CheckoutSession": { "description": "An envelope wrapping a list of checkout session objects.", "type": "object", "required": [ "checkout_sessions" ], "properties": { "checkout_sessions": { "description": "The list of checkout sessions.", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSession" } } }, "example": { "checkout_sessions": [ { "allow_promotion_codes": false, "amount_total": 2500, "amount_subtotal": 2500, "amount_received": 2500, "amount_refunded": 2500, "amount_disputed": 2500, "cancel_url": "https://example.com", "captures": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "disputes": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "capture_method": "automatic", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "example_value", "created_at": 2500, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "expires_at": 2500, "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "hsa_fsa_eligible": false, "letter_of_medical_necessity_required": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "mode": "payment", "origin": "shopify", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intents": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "redirect_url": "https://example.com", "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "shipping_address_collection": false, "shipping_details": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "open", "success_url": "https://example.com", "fees": [ { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } }, "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription_data": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "test_mode": false, "total_details": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "visit_type": "cbtSleep", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "next_action": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "selling_plans": [ { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } ], "shopify_payment_details": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } }, "renewal_as_of": 1781533800, "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "platform_fees": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } } ] } }, "CheckoutSessionBody_for_NewCheckoutSessionRequest": { "description": "An envelope wrapping a single checkout session object.", "type": "object", "required": [ "checkout_session" ], "properties": { "checkout_session": { "description": "The checkout session payload.", "$ref": "#/components/schemas/NewCheckoutSessionRequest" } }, "example": { "checkout_session": { "allow_promotion_codes": false, "line_items": [ { "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } }, "quantity": 0, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "tax_rate": { "amount": 2500 }, "components": [ { "quantity": 1.0, "dressing_mode": "MIXED", "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string" } ] } ], "cancel_url": "https://example.com", "capture_method": "automatic", "client_reference_id": "example_value", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "discounts": [ { "coupon_id": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "promo_code_id": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "coupon_data": { "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "name": "Coupon", "amount_off": 100, "duration": "once", "percent_off": 10.0, "max_redemptions": 100, "metadata": { "key": "value" } } } ], "mode": "payment", "metadata": { "order_id": "8842", "channel": "shopify" }, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "shipping_address_collection": false, "subscription_data": { "trial_end": "2026-06-15T14:30:00Z", "cancel_at": "2026-06-15T14:30:00Z", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "success_url": "https://example.com", "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "string", "fees": [ { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "amount": 2500, "fee_type": "lmn_consultation" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": false, "payment": { "message": "Premium SPF 50 mineral sunscreen" } } } } }, "NewCheckoutSessionRequest": { "description": "Parameters for creating a new Checkout Session.", "type": "object", "required": [ "line_items", "mode", "success_url" ], "properties": { "allow_promotion_codes": { "description": "Allows the session to be completed using a promotion code.", "type": [ "boolean", "null" ], "example": false }, "line_items": { "description": "A list of items the customer is purchasing. Use this parameter to pass one-time or recurring Prices.", "type": "array", "items": { "$ref": "#/components/schemas/NewLineItem" } }, "cancel_url": { "description": "URL the customer is redirected to if they cancel and return to your site. When set, the hosted checkout page displays a back button. `null` to omit the back button.", "type": [ "string", "null" ], "format": "uri", "example": "https://example.com" }, "capture_method": { "description": "Controls when funds are captured. One of `automatic` or `automatic_async` (capture immediately when the customer pays) or `manual` (authorize and capture later via the capture endpoint). `null` defaults to `automatic`.", "anyOf": [ { "$ref": "#/components/schemas/PaymentIntentCaptureMethod" }, { "type": "null" } ] }, "client_reference_id": { "description": "A unique string to reference the Checkout Session, such as a cart or order ID in your system. Use it to reconcile the session with your internal records.", "type": [ "string", "null" ], "example": "example_value" }, "defaults": { "description": "Customer details used to prefill the checkout page, or the ID of an existing Customer.", "anyOf": [ { "$ref": "#/components/schemas/CustomerDefaults" }, { "type": "null" } ] }, "discounts": { "description": "Discounts (coupons or promotion codes) to apply to the session. `null` to apply none.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DiscountType" } }, "mode": { "description": "The mode of the Checkout Session. One of `payment` (a one-time purchase), `subscription` (creates a subscription), `off_session` (charges a saved payment method without the customer present), or `setup` (saves a payment method without charging, e.g. for free trials). `reimbursement` (a letter for a purchase made elsewhere, charging only an explicit `lmn_consultation` fee) is in limited release and returns `mode_not_supported` unless enabled for your account.", "$ref": "#/components/schemas/Mode" }, "metadata": { "description": "Set of key-value pairs you can attach to the session for storing additional structured information.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "shipping_options": { "description": "Shipping rate options to apply to the session. `null` to charge no shipping.", "anyOf": [ { "$ref": "#/components/schemas/ShippingRateOptionsRequest" }, { "type": "null" } ] }, "shipping_address_collection": { "description": "When `true`, the hosted checkout page collects a shipping address from the customer. `null` defaults to `false`.", "type": [ "boolean", "null" ], "example": false }, "subscription_data": { "description": "Data used to create the subscription. Required when `mode` is `subscription`.", "anyOf": [ { "$ref": "#/components/schemas/NewSubscriptionDataRequest" }, { "type": "null" } ] }, "success_url": { "description": "URL the customer is redirected to after the payment or subscription creation succeeds.", "type": "string", "format": "uri", "example": "https://example.com" }, "tax_rate": { "description": "A fixed tax amount to apply to the session. Use this to pass tax you have computed yourself instead of having Flex calculate it. `null` to apply no fixed tax.", "anyOf": [ { "$ref": "#/components/schemas/TaxRate" }, { "type": "null" } ] }, "tax_calculation_mode": { "description": "When Flex calculates tax, whether the provided amounts are `exclusive` or `inclusive` of tax. `null` means Flex does not calculate tax; pass `tax_rate` instead.", "anyOf": [ { "$ref": "#/components/schemas/TaxCalculationMode" }, { "type": "null" } ] }, "setup_future_use": { "description": "How the payment method may be used in the future. One of `on_session` (Default; standard payments requiring customer authentication) or `off_session` (allows future charges without the customer present). `null` defaults to `on_session`.", "anyOf": [ { "$ref": "#/components/schemas/FutureUse" }, { "type": "null" } ] }, "payment_method_options": { "description": "Payment method-specific options for the session, such as 3D Secure preferences.", "anyOf": [ { "$ref": "#/components/schemas/PaymentMethodOptionsRequest" }, { "type": "null" } ] }, "payment_method": { "description": "A saved payment method to charge for an off-session checkout. Provide a single payment method ID, or a pair of payment methods for a split (HSA/FSA + standard) cart.", "anyOf": [ { "$ref": "#/components/schemas/OffSessionPaymentMethod" }, { "type": "null" } ] }, "customer": { "description": "The ID of an existing Customer, or customer details to prefill the checkout page. `null` to leave the customer unset.", "type": [ "string", "null" ] }, "fees": { "description": "Additional fees to add to the session, such as consultation or service fees. `null` to add none.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/NewFeeRequest" } }, "custom_text": { "description": "Custom text to display to the customer on the hosted checkout page. `null` to use the default text.", "anyOf": [ { "$ref": "#/components/schemas/NewCustomTextRequest" }, { "type": "null" } ] } }, "example": { "allow_promotion_codes": false, "line_items": [ { "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } }, "quantity": 0, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "tax_rate": { "amount": 2500 }, "components": [ { "quantity": 1.0, "dressing_mode": "MIXED", "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string" } ] } ], "cancel_url": "https://example.com", "capture_method": "automatic", "client_reference_id": "example_value", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "discounts": [ { "coupon_id": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "promo_code_id": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "coupon_data": { "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "name": "Coupon", "amount_off": 100, "duration": "once", "percent_off": 10.0, "max_redemptions": 100, "metadata": { "key": "value" } } } ], "mode": "payment", "metadata": { "order_id": "8842", "channel": "shopify" }, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "shipping_address_collection": false, "subscription_data": { "trial_end": "2026-06-15T14:30:00Z", "cancel_at": "2026-06-15T14:30:00Z", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "success_url": "https://example.com", "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "string", "fees": [ { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "amount": 2500, "fee_type": "lmn_consultation" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": false, "payment": { "message": "Premium SPF 50 mineral sunscreen" } } } }, "NewLineItem": { "description": "A line item to add to a Checkout Session, referencing an existing Price or supplying inline price data, together with the quantity and any per-item shipping or tax.", "type": "object", "required": [ "quantity" ], "properties": { "price": { "description": "The ID of the Price object. One of price or price_data is required. If both are sent, price wins and price_data is ignored.", "type": [ "string", "null" ], "example": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "price_data": { "description": "Data used to generate a new Price object inline. One of price or price_data is required. If both are sent, price wins and price_data is ignored; price_data alone is used as-sent.", "anyOf": [ { "$ref": "#/components/schemas/InlinePriceDataRequest" }, { "type": "null" } ] }, "quantity": { "description": "The quantity of the line item being purchased.", "type": "integer", "format": "int32", "minimum": -2147483648.0, "maximum": 2147483647.0 }, "shipping_options": { "description": "Shipping rate options for the line item.", "anyOf": [ { "$ref": "#/components/schemas/ShippingRateOptionsRequest" }, { "type": "null" } ] }, "tax_rate": { "description": "Tax rate for a specific line item", "anyOf": [ { "$ref": "#/components/schemas/TaxRate" }, { "type": "null" } ] }, "components": { "description": "The components of this line item's build, e.g. the ingredients of a bowl. A supplied list is the whole build for this order and is never merged with anything stored on the product. Omit it entirely for a fixed-recipe product, whose build is read from its own `medical_meal_recipe_v1` metadata instead; an explicit empty list is rejected. Each entry names its component by `component_id` or by your own `client_reference_id`, and must resolve to a component you own or a shared one. At most 50 entries per line item.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/LineItemComponent" }, "maxItems": 50 } }, "example": { "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } }, "quantity": 0, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "tax_rate": { "amount": 2500 }, "components": [ { "quantity": 1.0, "dressing_mode": "MIXED", "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string" } ] } }, "InlinePriceDataRequest": { "description": "The shape of a price defined inline on another resource, as `price_data`. Reference an existing product with `product`, or create one inline with `product_data`.", "type": "object", "properties": { "description": { "description": "A brief description of the price.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" }, "unit_amount": { "description": "A positive integer in cents (or 0 for a free price) representing how much to charge.", "type": "integer", "format": "int64", "minimum": 0.0, "example": 2500, "maximum": 4294967295.0 }, "recurring": { "description": "The recurring components of a price such as interval and trial period days.", "anyOf": [ { "$ref": "#/components/schemas/Recurring" }, { "type": "null" } ] }, "metadata": { "description": "Metadata to attach to the price.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "product": { "description": "The ID of the product that this price will belong to.", "type": "string", "example": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "product_data": { "description": "Data used to generate a new Product object inline.", "$ref": "#/components/schemas/CreateProductRequest" } }, "required": [ "unit_amount" ], "example": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } } }, "CreateProductRequest": { "description": "Parameters for creating a product. HSA/FSA eligibility is determined automatically by Flex from the name, description, and identifiers you provide, and cannot be set directly.", "type": "object", "required": [ "name" ], "properties": { "name": { "description": "The product's name, meant to be displayed to the customer.", "type": "string", "example": "Example" }, "description": { "description": "The product's description, a short blurb meant to be displayed to the customer.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" }, "upc_code": { "description": "The product's UPC code. If provided, this will be used to check whether the product is on the eligible product list.", "type": [ "string", "null" ], "example": "example_value" }, "gtin": { "description": "The product's GTIN. If provided, this will be used to check whether the product is on the eligible product list.", "type": [ "string", "null" ], "example": "example_value" }, "reference_gtin": { "description": "If the product is HSA/FSA eligible through private label, this should be provided.", "type": [ "string", "null" ], "example": "example_value" }, "url": { "description": "A URL of a publicly-accessible image of the product.", "type": [ "string", "null" ], "example": "https://example.com" }, "client_reference_id": { "description": "An optional identifier for the product set by the client. Immutable after creation.", "type": [ "string", "null" ], "example": "example_value" }, "metadata": { "description": "Set of key-value pairs that you can attach to a product. This can be useful for storing additional information about the product in a structured format.", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": { "order_id": "8842", "channel": "shopify" } }, "image_urls": { "description": "URLs of publicly-accessible product images for eligibility determination.", "type": [ "array", "null" ], "items": { "type": "string" }, "example": [ "https://example.com/image.png" ] }, "categories": { "description": "Product categories (e.g., \"Vitamins\", \"First Aid\").", "type": [ "array", "null" ], "items": { "type": "string" } }, "components": { "description": "Product components or ingredients (e.g., \"Vitamin C\", \"Zinc\").", "type": [ "array", "null" ], "items": { "type": "string" } } }, "example": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } }, "ShippingRateOptionsRequest": { "description": "Specifies the shipping rate to apply, either by referencing an existing rate or by providing inline data to create one. Provide one of `shipping_rate_id` or `shipping_rate_data`; at least one is required.", "type": "object", "properties": { "shipping_rate_id": { "description": "ID of an existing shipping rate to apply. Provide this or `shipping_rate_data`.", "type": [ "string", "null" ], "example": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "shipping_rate_data": { "description": "Inline shipping rate parameters used to create a new shipping rate. Provide this or `shipping_rate_id`.", "anyOf": [ { "$ref": "#/components/schemas/CreateShippingRateRequest" }, { "type": "null" } ] } }, "example": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } } }, "LineItemComponent": { "description": "One component of a line item's build, as sent at checkout.", "type": "object", "properties": { "quantity": { "description": "How many portions of the component. A standard build is `1.0`, which is also the default when omitted. Must be a positive, finite number.", "default": 1.0, "type": "number", "format": "double", "example": 1.0 }, "dressing_mode": { "description": "How the dressing was ordered: mixed into the bowl or served on the side. Only meaningful for dressing components; ignored otherwise. A mixed-in dressing counts toward eligibility gating, an on-the-side one does not, and an omitted mode is treated as mixed in (the conservative direction). Taken as sent — not cross-checked against the catalog.", "anyOf": [ { "$ref": "#/components/schemas/DressingMode" }, { "type": "null" } ] }, "component_id": { "description": "The component's `fcomp_` identifier, from `/v1/product_components`. The component must be one of yours or one of Flex's shared components. Each entry names at least one of `component_id` or `client_reference_id`; if both are sent, `component_id` wins and the reference is ignored.", "type": "string", "example": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "client_reference_id": { "description": "Your own identifier for the component, as registered on `/v1/product_components` (CON-1550). Each entry names at least one of `component_id` or `client_reference_id`; if both are sent, `component_id` wins and the reference is ignored.", "type": "string" } }, "example": { "quantity": 1.0, "dressing_mode": "MIXED", "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string" } }, "DressingMode": { "description": "How a dressing component was ordered, as sent at checkout.\n\nWire values are the partner payload agreement's (`MIXED` / `ON_THE_SIDE`); the eligibility engine's [`DressingPlacement`] is the internal counterpart, reached only through the [`From`] mapping below so the wire shape and the engine shape can evolve independently.", "type": "string", "enum": [ "MIXED", "ON_THE_SIDE" ], "example": "MIXED" }, "DiscountType": { "description": "Specifies a discount to apply, as one of: an existing coupon referenced by ID, an existing promotion code referenced by ID, or inline coupon data to create a new coupon and apply it.", "type": "object", "properties": { "coupon_id": { "description": "ID of an existing Coupon to apply.", "type": "string", "example": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "promo_code_id": { "description": "ID of an existing PromoCode to apply. The discount is sourced from the coupon the promotion code references.", "type": "string", "example": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "coupon_data": { "description": "Inline coupon parameters used to create a new Coupon, which is then applied.", "$ref": "#/components/schemas/CreateCouponRequest" } }, "example": { "coupon_id": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "promo_code_id": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "coupon_data": { "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "name": "Coupon", "amount_off": 100, "duration": "once", "percent_off": 10.0, "max_redemptions": 100, "metadata": { "key": "value" } } } }, "CreateCouponRequest": { "description": "Parameters for creating a coupon. Exactly one of `amount_off` or `percent_off` must be set.", "type": "object", "required": [ "name" ], "properties": { "applies_to": { "description": "An object containing directions for what this Coupon will apply discounts to. If null, the coupon applies to the entire order.", "anyOf": [ { "$ref": "#/components/schemas/AppliesTo" }, { "type": "null" } ] }, "name": { "description": "Name of the coupon displayed to customers.", "type": "string", "example": "Coupon" }, "amount_off": { "description": "A positive integer representing the amount to subtract from an invoice total (required if percent_off is not passed).", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 100, "minimum": -2147483648.0 }, "duration": { "description": "Specifies how long the discount will be in effect if used on a subscription. Defaults to once.", "anyOf": [ { "$ref": "#/components/schemas/CouponDuration" }, { "type": "null" } ], "example": "once" }, "duration_in_months": { "description": "Required only if duration is repeating, in which case it must be a positive integer that specifies the number of months the discount will be in effect.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "percent_off": { "description": "A positive float larger than 0, and smaller or equal to 100, that represents the discount the coupon will apply (required if amount_off is not passed).", "type": [ "number", "null" ], "format": "double", "example": 10.0 }, "max_redemptions": { "description": "A positive integer specifying the number of times the coupon can be redeemed before it’s no longer valid.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 100, "minimum": -2147483648.0 }, "metadata": { "description": "Metadata to attach to this coupon.", "type": [ "object", "null" ], "example": { "key": "value" } } }, "example": { "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "name": "Coupon", "amount_off": 100, "duration": "once", "percent_off": 10.0, "max_redemptions": 100, "metadata": { "key": "value" } } }, "NewSubscriptionDataRequest": { "description": "Trial and cancellation settings to apply to the subscription created when a checkout session completes. Provided as `subscription_data` when creating a checkout session in subscription mode.", "type": "object", "properties": { "trial_end": { "description": "ISO 8601 timestamp at which the trial period ends for the subscription created at checkout. Use this when you need a precise trial-end time — for example, a 6.5-day trial, or a trial that ends within an ad-network's attribution window. Mutually exclusive with `trial_period_days`; pass at most one.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" }, "cancel_at": { "description": "A future ISO 8601 timestamp at which the created subscription will automatically be canceled. Omit to leave the subscription open-ended.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" }, "cancel_at_period_end": { "description": "If `true`, the created subscription cancels at the end of its first billing period rather than renewing. Defaults to `false` when omitted.", "type": [ "boolean", "null" ], "example": false }, "trial_period_days": { "description": "Length of the trial period, in days, for the created subscription. Mutually exclusive with `trial_end`; pass at most one.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "minimum": -2147483648.0 }, "trial_settings": { "description": "Optional Stripe-compatible trial-end behavior. Omit this object to preserve existing behavior. Currently, `cancel` is the only supported value.", "anyOf": [ { "$ref": "#/components/schemas/SubscriptionTrialSettings" }, { "type": "null" } ] }, "backup_payment_method": { "description": "Collect a second card at checkout that Flex charges when a renewal on the primary card fails. `required` blocks checkout until the shopper provides one; `optional` lets the shopper skip it, but a card they enter that fails is reported. Omit to use the partner's `subscription_backup_payment_method` default.", "anyOf": [ { "$ref": "#/components/schemas/BackupPaymentMethodRequirement" }, { "type": "null" } ] } }, "example": { "trial_end": "2026-06-15T14:30:00Z", "cancel_at": "2026-06-15T14:30:00Z", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } } }, "PaymentMethodOptionsRequest": { "description": "Payment method-specific options to apply when creating a Checkout Session.", "type": "object", "properties": { "card": { "description": "Options that apply to card payments. `null` to use the defaults.", "anyOf": [ { "$ref": "#/components/schemas/CardPaymentMethodOptionsRequest" }, { "type": "null" } ] } }, "example": { "card": { "request_three_d_secure": "automatic" } } }, "CardPaymentMethodOptionsRequest": { "description": "Card-specific payment options to apply when creating a Checkout Session.", "type": "object", "properties": { "request_three_d_secure": { "description": "Whether to request 3D Secure authentication for card payments. One of `automatic` (Default; request only when required), `any` (request whenever supported), or `challenge` (request a customer challenge). `null` defaults to `automatic`.", "anyOf": [ { "$ref": "#/components/schemas/RequestThreeDSecure" }, { "type": "null" } ] } }, "example": { "request_three_d_secure": "automatic" } }, "OffSessionPaymentMethod": { "description": "The saved payment method(s) to charge for an off-session checkout: either a single PaymentMethod ID to charge the full amount, or a pair of PaymentMethod IDs to split the charge across the HSA/FSA-eligible and non-eligible portions of the cart.", "anyOf": [ { "type": "string", "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, { "$ref": "#/components/schemas/SplitCartPaymentMethod" } ], "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "SplitCartPaymentMethod": { "description": "A pair of saved payment methods for an off-session split-cart checkout: one to charge the HSA/FSA-eligible items and one to charge the non-eligible items.", "type": "object", "required": [ "eligible_payment_method", "ineligible_payment_method" ], "properties": { "eligible_payment_method": { "description": "ID of the PaymentMethod used to charge the HSA/FSA-eligible portion of the cart.", "type": "string", "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "ineligible_payment_method": { "description": "ID of the PaymentMethod used to charge the non-eligible portion of the cart.", "type": "string", "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "example": { "eligible_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "ineligible_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "NewFeeRequest": { "description": "An additional fee to add to a Checkout Session, such as a consultation or service fee.", "type": "object", "required": [ "amount", "fee_type" ], "properties": { "name": { "description": "A short name for the fee, shown to the customer at checkout.", "type": [ "string", "null" ], "example": "Example" }, "description": { "description": "A longer description of the fee, shown to the customer at checkout.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" }, "amount": { "description": "The fee amount, in the smallest currency unit (e.g., `1500` = $15.00 USD).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "fee_type": { "description": "The kind of fee. `lmn_consultation` is charged only when a Letter of Medical Necessity is required. A coupon scoped to either fee type can reduce that type's payable contribution.", "$ref": "#/components/schemas/FeeType" } }, "example": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "amount": 2500, "fee_type": "lmn_consultation" } }, "NewCustomTextRequest": { "description": "Custom text to display to the customer at various points on the hosted checkout page. Each field is optional; omit a field to use the default text.", "type": "object", "properties": { "after_submit": { "description": "Custom text shown after the customer submits payment. `null` to use the default.", "anyOf": [ { "$ref": "#/components/schemas/CustomTextMessage" }, { "type": "null" } ] }, "shipping_address": { "description": "Custom text shown in the shipping address collection section. `null` to use the default.", "anyOf": [ { "$ref": "#/components/schemas/CustomTextMessage" }, { "type": "null" } ] }, "submit": { "description": "Custom text shown near the submit (pay) button. `null` to use the default.", "anyOf": [ { "$ref": "#/components/schemas/CustomTextMessage" }, { "type": "null" } ] }, "terms_of_service_acceptance": { "description": "Custom text shown alongside the terms of service acceptance. `null` to use the default.", "anyOf": [ { "$ref": "#/components/schemas/CustomTextMessage" }, { "type": "null" } ] }, "terms_of_service_checkbox_required": { "description": "Whether the customer must check a terms of service checkbox before paying. `null` to use the default.", "type": [ "boolean", "null" ], "example": false }, "payment": { "description": "Custom text shown in the payment section. `null` to use the default.", "anyOf": [ { "$ref": "#/components/schemas/CustomTextMessage" }, { "type": "null" } ] } }, "example": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": false, "payment": { "message": "Premium SPF 50 mineral sunscreen" } } }, "CheckoutSessionBody_for_CheckoutSession": { "description": "An envelope wrapping a single checkout session object.", "type": "object", "required": [ "checkout_session" ], "properties": { "checkout_session": { "description": "The checkout session payload.", "$ref": "#/components/schemas/CheckoutSession" } }, "example": { "checkout_session": { "allow_promotion_codes": false, "amount_total": 2500, "amount_subtotal": 2500, "amount_received": 2500, "amount_refunded": 2500, "amount_disputed": 2500, "cancel_url": "https://example.com", "captures": [ "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "disputes": [ "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "capture_method": "automatic", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "example_value", "created_at": 2500, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "defaults": { "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone": "+14155550142" }, "expires_at": 2500, "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "hsa_fsa_eligible": false, "letter_of_medical_necessity_required": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "mode": "payment", "origin": "shopify", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intents": [ "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "redirect_url": "https://example.com", "refunds": [ "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "shipping_address_collection": false, "shipping_details": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "open", "success_url": "https://example.com", "fees": [ { "fee_id": "ffee_1234567890", "amount": 2500, "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "fee_type": "lmn_consultation", "applied": true, "waived_reason": "existing_letter" } ], "custom_text": { "after_submit": { "message": "Premium SPF 50 mineral sunscreen" }, "shipping_address": { "message": "Premium SPF 50 mineral sunscreen" }, "submit": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_acceptance": { "message": "Premium SPF 50 mineral sunscreen" }, "terms_of_service_checkbox_required": true, "payment": { "message": "Premium SPF 50 mineral sunscreen" } }, "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription_data": { "cancel_at": "2026-06-15T14:30:00Z", "trial_end": "string", "cancel_at_period_end": false, "trial_period_days": 0, "trial_settings": { "end_behavior": { "missing_payment_method": "cancel" } } }, "tax_rate": { "amount": 2500 }, "tax_calculation_mode": "exclusive", "test_mode": false, "total_details": { "amount_discount": 2500, "amount_tax": 2500, "amount_shipping": 2500, "amount_iias": 2500, "amount_vision": 2500, "amount_prescription": 2500, "amount_service": 2500, "amount_fee": 2500, "breakdown": { "discounts": [ { "discount": { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } } ] } }, "visit_type": "cbtSleep", "setup_future_use": "on_session", "payment_method_options": { "card": { "request_three_d_secure": "automatic" } }, "next_action": { "type": "collect_letter_of_medical_necessity", "collect_letter_of_medical_necessity": { "url": "https://example.com" }, "payment_failed": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "decline_code": "string", "error_code": "string" }, "provide_second_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com", "eligible_amount": 0, "ineligible_amount": 0 }, "provide_alternative_payment_method": { "message": "Premium SPF 50 mineral sunscreen", "url": "https://example.com" } }, "selling_plans": [ { "id": "string", "name": "string", "billing_interval": { "interval": "day", "interval_count": 0 } } ], "shopify_payment_details": { "gateway": "string", "wallet": "string", "card": { "brand": "american_express", "last4": "4242" } }, "renewal_as_of": 1781533800, "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "platform_fees": { "letter_fee": { "amount": 2500, "type": "string", "status": "pending" } } } } }, "MultipleLineItemsBody_for_LineItem": { "description": "An envelope wrapping a list of line item objects.", "type": "object", "required": [ "line_items" ], "properties": { "line_items": { "description": "The list of line items.", "type": "array", "items": { "$ref": "#/components/schemas/LineItem" } } }, "example": { "line_items": [ { "line_item_id": "fli_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount_discount": 2500, "amount_subtotal": 2500, "amount_tax": 2500, "amount_total": 2500, "amount_shipping": 2500, "amount_fee": 2500, "description": "Premium SPF 50 mineral sunscreen", "fees": [ { "fee_type": "lmn_consultation", "amount": 2500 } ], "price": { "price_id": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "trial_period_days": 0, "unit_amount": 0, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "active": false, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "type": "one_time", "metadata": { "order_id": "8842", "channel": "shopify" }, "lookup_key": "standard_monthly", "hsa_fsa_eligibility": "not_eligible", "test_mode": false }, "quantity": 2500, "eligibility": "not_eligible", "shipping_rate": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ] } }, "LineItem": { "description": "A LineItem represents a single product on a checkout session, with its per-item pricing breakdown (subtotal, discount, tax, shipping, fees) and its HSA/FSA eligibility classification.", "type": "object", "required": [ "amount_discount", "amount_fee", "amount_shipping", "amount_subtotal", "amount_tax", "amount_total", "description", "eligibility", "fees", "line_item_id", "price", "quantity" ], "properties": { "line_item_id": { "description": "Unique identifier for the line item, prefixed with `fli_`.", "type": "string", "example": "fli_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "amount_discount": { "description": "Total discount applied to the line item, in the smallest currency unit (e.g., `500` = $5.00 USD). `0` if no discount applies.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_subtotal": { "description": "Subtotal for the line item before tax, shipping, discounts, and fees, in the smallest currency unit (e.g., `2500` = $25.00 USD).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_tax": { "description": "Tax applied to the line item, in the smallest currency unit (e.g., `200` = $2.00 USD). `0` if no tax applies.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_total": { "description": "Total amount charged for the line item including tax, shipping, and fees and net of discounts, in the smallest currency unit (e.g., `2700` = $27.00 USD).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_shipping": { "description": "Shipping charged on the line item, in the smallest currency unit (e.g., `500` = $5.00 USD). `0` if no shipping applies.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "amount_fee": { "description": "Total fees charged on the line item, in the smallest currency unit (e.g., `100` = $1.00 USD). `0` if no fees apply. See `fees` for the per-type breakdown.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "description": { "description": "Description of the line item, typically the product name.", "type": "string", "example": "Premium SPF 50 mineral sunscreen" }, "fees": { "description": "The fees associated with this line item.", "type": "array", "items": { "$ref": "#/components/schemas/LineItemFee" } }, "price": { "description": "The Price object this line item was purchased at.", "$ref": "#/components/schemas/Price" }, "quantity": { "description": "Quantity of the product purchased.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "eligibility": { "description": "The HSA/FSA eligibility classification for this line item.", "$ref": "#/components/schemas/HSAFSAElegibility" }, "shipping_rate": { "description": "ID of the Shipping Rate applied to this line item, if one was selected.", "type": [ "string", "null" ], "example": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "example": { "line_item_id": "fli_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount_discount": 2500, "amount_subtotal": 2500, "amount_tax": 2500, "amount_total": 2500, "amount_shipping": 2500, "amount_fee": 2500, "description": "Premium SPF 50 mineral sunscreen", "fees": [ { "fee_type": "lmn_consultation", "amount": 2500 } ], "price": { "price_id": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "trial_period_days": 0, "unit_amount": 0, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "active": false, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "type": "one_time", "metadata": { "order_id": "8842", "channel": "shopify" }, "lookup_key": "standard_monthly", "hsa_fsa_eligibility": "not_eligible", "test_mode": false }, "quantity": 2500, "eligibility": "not_eligible", "shipping_rate": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "LineItemFee": { "description": "A fee associated with a line item.", "type": "object", "required": [ "amount", "fee_type" ], "properties": { "fee_type": { "description": "The type of the fee.", "$ref": "#/components/schemas/FeeType" }, "amount": { "description": "The amount of the fee in cents that applies to this item.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 } }, "example": { "fee_type": "lmn_consultation", "amount": 2500 } }, "CheckoutSessionBody_for_ConfirmCheckoutSessionRequest": { "description": "An envelope wrapping a single checkout session object.", "type": "object", "required": [ "checkout_session" ], "properties": { "checkout_session": { "description": "The checkout session payload.", "$ref": "#/components/schemas/ConfirmCheckoutSessionRequest" } }, "example": { "checkout_session": { "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "capture_method": "automatic" } } }, "ConfirmCheckoutSessionRequest": { "description": "Parameters for confirming the eligible-only charge on a Checkout Session.\n\nDeliberately just these two fields. There is **no `customer`**: the session already resolved its own customer when the split was computed, and the payment method must belong to that customer or the confirm is refused — a body `customer` would be redundant at best and a second source of truth at worst. Nor is there an `amount`: binding the charge to the persisted `food_eligibility_record.eligible_cents` is the point of the feature, so no caller gets to pass an amount in and drift from the audit row.", "type": "object", "required": [ "capture_method", "payment_method" ], "properties": { "payment_method": { "description": "ID of the saved PaymentMethod to charge. It must belong to the Checkout Session's customer and have been saved for off-session use.", "type": "string", "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "capture_method": { "description": "Must be `automatic`, which captures the funds immediately.\n\n`manual` is rejected with `manual_capture_not_supported` (422). It would authorize successfully and then be uncapturable: the capture endpoint gates on the *session's* `capture_method`, which confirm cannot write, so the hold would sit on the customer's card until it expired. The field is kept — rather than dropped and hardcoded — so that enabling `manual` later is a server-side change and not a breaking one for anyone already sending it.", "$ref": "#/components/schemas/PaymentIntentCaptureMethod" } }, "example": { "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "capture_method": "automatic" } }, "CheckoutSessionBody_for_CaptureCheckoutSessionRequest": { "description": "An envelope wrapping a single checkout session object.", "type": "object", "required": [ "checkout_session" ], "properties": { "checkout_session": { "description": "The checkout session payload.", "$ref": "#/components/schemas/CaptureCheckoutSessionRequest" } }, "example": { "checkout_session": { "final_capture": false, "line_items": [ { "amount_to_capture": 2500, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "metadata": { "order_id": "8842", "channel": "shopify" }, "capture_metadata": { "order_id": "8842", "channel": "shopify" }, "amount_shipping": 2500, "amount_discount": 2500, "amount_tax": 2500 } } }, "CaptureCheckoutSessionRequest": { "description": "Parameters for capturing funds previously authorized on a Checkout Session.", "type": "object", "properties": { "final_capture": { "description": "Whether this is the final capture. When `true`, any uncaptured authorized amount is released; when `false` (Default), the remaining amount stays authorized and can be captured by a subsequent request. `null` defaults to `false`.", "type": [ "boolean", "null" ], "example": false }, "line_items": { "description": "The specific line items and amounts to capture. Omit to capture the full authorized amount across all line items.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/LineItemCaptureRequest" } }, "metadata": { "description": "Set of key-value pairs to attach to the capture for storing additional structured information.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "capture_metadata": { "description": "Set of key-value pairs to set on the Checkout Session's `metadata` when the capture succeeds. `null` to leave the session metadata unchanged.", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": { "order_id": "8842", "channel": "shopify" } }, "amount_shipping": { "description": "Portion of the captured amount attributable to shipping, in the smallest currency unit (e.g., `599` = $5.99 USD).", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_discount": { "description": "Portion of the captured amount attributable to discounts, in the smallest currency unit (e.g., `500` = $5.00 USD).", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_tax": { "description": "Portion of the captured amount attributable to tax, in the smallest currency unit (e.g., `175` = $1.75 USD).", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 } }, "example": { "final_capture": false, "line_items": [ { "amount_to_capture": 2500, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "metadata": { "order_id": "8842", "channel": "shopify" }, "capture_metadata": { "order_id": "8842", "channel": "shopify" }, "amount_shipping": 2500, "amount_discount": 2500, "amount_tax": 2500 } }, "LineItemCaptureRequest": { "description": "Identifies a single line item to capture and how much of it to capture.", "type": "object", "properties": { "amount_to_capture": { "description": "The amount to capture for this line item, in the smallest currency unit (e.g., `2500` = $25.00 USD). Omit to capture the full authorized amount for the item.", "type": [ "integer", "null" ], "format": "int64", "minimum": 0.0, "maximum": 4294967295.0, "example": 2500 }, "product": { "type": "string", "example": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "ID of the Product identifying the line item." }, "price": { "type": "string", "example": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "ID of the Price identifying the line item." } }, "example": { "amount_to_capture": 2500, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "CaptureAllocationResponse": { "description": "Preview of how a capture would be distributed across the session's payment methods.", "type": "object", "required": [ "allocations" ], "properties": { "allocations": { "description": "The computed capture amount allocated to each payment method. No capture is executed.", "type": "array", "items": { "$ref": "#/components/schemas/CaptureAllocation" } } }, "example": { "allocations": [ { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "last4": "4242", "amount": 2500 } ] } }, "CaptureAllocation": { "description": "How much of a capture is allocated to a specific payment method.", "type": "object", "required": [ "amount", "last4", "payment_method_id" ], "properties": { "payment_method_id": { "description": "ID of the PaymentMethod this portion of the capture is allocated to.", "type": "string", "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "last4": { "description": "The last four digits of the card backing this payment method. `\"unknown\"` if the card details could not be resolved.", "type": "string", "example": "4242" }, "amount": { "description": "Amount allocated to this payment method, in the smallest currency unit (e.g., `2500` = $25.00 USD).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 } }, "example": { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "last4": "4242", "amount": 2500 } }, "CheckoutSessionBody_for_ReauthCheckoutSessionRequest": { "description": "An envelope wrapping a single checkout session object.", "type": "object", "required": [ "checkout_session" ], "properties": { "checkout_session": { "description": "The checkout session payload.", "$ref": "#/components/schemas/ReauthCheckoutSessionRequest" } }, "example": { "checkout_session": { "amount_override": 2500 } } }, "ReauthCheckoutSessionRequest": { "description": "Parameters for re-authorizing the payment on a Checkout Session.", "type": "object", "properties": { "amount_override": { "description": "Amount to authorize on the new payment intent, in the smallest currency unit (e.g., `5000` = $50.00 USD). `null` re-authorizes the remaining amount (the session total minus what has already been captured).", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 } }, "example": { "amount_override": 2500 } }, "CheckoutSessionBody_for_RefundCheckoutSessionRequest": { "description": "An envelope wrapping a single checkout session object.", "type": "object", "required": [ "checkout_session" ], "properties": { "checkout_session": { "description": "The checkout session payload.", "$ref": "#/components/schemas/RefundCheckoutSessionRequest" } }, "example": { "checkout_session": { "refund_metadata": { "order_id": "8842", "channel": "shopify" }, "amount_tax": 2500, "amount_shipping": 2500, "amount_discount": 2500, "payment_methods": [ { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500 } ], "line_items": [ { "amount_to_refund": 2500, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "amount": 0 } } }, "RefundCheckoutSessionRequest": { "description": "Parameters for refunding a Checkout Session. Specify what to refund either by `line_items` or by a total `amount`; omit both to refund the full remaining amount.", "type": "object", "properties": { "refund_metadata": { "description": "Set of key-value pairs to set on the Checkout Session's `metadata` when the refund succeeds. `null` to leave the session metadata unchanged.", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": { "order_id": "8842", "channel": "shopify" } }, "amount_tax": { "description": "Portion of the refund attributable to tax, in the smallest currency unit (e.g., `175` = $1.75 USD).", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_shipping": { "description": "Portion of the refund attributable to shipping, in the smallest currency unit (e.g., `599` = $5.99 USD).", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "amount_discount": { "description": "Portion of the refund attributable to discounts, in the smallest currency unit (e.g., `500` = $5.00 USD).", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "payment_methods": { "description": "Explicit allocation to specific payment methods. When provided, bypasses automatic HSA-based allocation and refunds exact amounts to each payment method. This feature is currently in beta. Contact the Flex team to request access.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PaymentMethodRefundRequest" } }, "line_items": { "description": "The line items to refund, with the amount to refund for each.", "type": "array", "items": { "$ref": "#/components/schemas/LineItemRefundRequest" } }, "amount": { "description": "The total amount to refund, in the smallest currency unit (e.g., `2500` = $25.00 USD).", "type": "integer", "format": "int64", "minimum": 0.0, "maximum": 4294967295.0 } }, "example": { "refund_metadata": { "order_id": "8842", "channel": "shopify" }, "amount_tax": 2500, "amount_shipping": 2500, "amount_discount": 2500, "payment_methods": [ { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500 } ], "line_items": [ { "amount_to_refund": 2500, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ], "amount": 0 } }, "PaymentMethodRefundRequest": { "description": "Request to refund a specific amount to a specific payment method.\n\nWhen multiple `PaymentMethodRefundRequest` entries have the same `payment_method_id`, their amounts are aggregated during validation.\n\n# Fields * `payment_method_id` - The payment method to refund to * `amount` - Amount to refund in cents (must be non-negative)", "type": "object", "required": [ "amount", "payment_method_id" ], "properties": { "payment_method_id": { "description": "ID of the PaymentMethod to refund to.", "type": "string", "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "amount": { "description": "Amount to refund to this payment method, in the smallest currency unit (e.g., `2500` = $25.00 USD). Must be non-negative.", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 } }, "example": { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500 } }, "LineItemRefundRequest": { "description": "Identifies a single line item to refund and how much of it to refund.", "type": "object", "properties": { "amount_to_refund": { "description": "The amount to refund for this line item, in the smallest currency unit (e.g., `2500` = $25.00 USD). Omit to refund the full amount for the item.", "type": [ "integer", "null" ], "format": "int64", "minimum": 0.0, "maximum": 4294967295.0, "example": 2500 }, "product": { "type": "string", "example": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "ID of the Product identifying the line item." }, "price": { "type": "string", "example": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "ID of the Price identifying the line item." } }, "example": { "amount_to_refund": 2500, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "RefundAllocationResponse": { "description": "Preview of how a refund would be distributed across the session's payment methods.", "type": "object", "required": [ "allocations" ], "properties": { "allocations": { "description": "The computed refund amount allocated to each payment method. No refund is executed.", "type": "array", "items": { "$ref": "#/components/schemas/RefundAllocation" } } }, "example": { "allocations": [ { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "last4": "4242", "amount": 2500 } ] } }, "RefundAllocation": { "description": "How much of a refund is allocated to a specific payment method.", "type": "object", "required": [ "amount", "last4", "payment_method_id" ], "properties": { "payment_method_id": { "description": "ID of the PaymentMethod this portion of the refund would be returned to.", "type": "string", "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "last4": { "description": "Last four digits of the payment method's card, for display. Falls back to `\"unknown\"` if it cannot be resolved.", "type": "string", "example": "4242" }, "amount": { "description": "Amount that would be refunded to this payment method, in the smallest currency unit (e.g., `2500` = $25.00 USD).", "type": "integer", "format": "int64", "example": 2500, "minimum": -9007199254740991.0, "maximum": 9007199254740991.0 } }, "example": { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "last4": "4242", "amount": 2500 } }, "ResendReceiptsResponse": { "description": "Response returned after queuing receipt emails for resending.", "type": "object", "required": [ "receipt_ids" ], "properties": { "receipt_ids": { "description": "The receipt IDs that were queued for resending.", "type": "array", "items": { "type": "string" } } }, "example": { "receipt_ids": [ "string" ] } }, "ResendLomnResponse": { "description": "Response returned after queuing Letter of Medical Necessity (LOMN) emails for resending.", "type": "object", "required": [ "consultation_ids" ], "properties": { "consultation_ids": { "description": "The consultation IDs that were queued for LOMN email resending.", "type": "array", "items": { "type": "string" } } }, "example": { "consultation_ids": [ "string" ] } }, "MultipleCouponsBody_for_V1Coupon": { "description": "An envelope wrapping a list of coupon objects.", "type": "object", "required": [ "coupons" ], "properties": { "coupons": { "description": "The list of coupons.", "type": "array", "items": { "$ref": "#/components/schemas/V1Coupon" } } }, "example": { "coupons": [ { "coupon_id": "fcoup_1234567890", "amount_off": 2500, "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "duration": "once", "duration_in_months": 0, "metadata": { "order_id": "8842", "channel": "shopify" }, "name": "Example", "percent_off": 0.0, "max_redemptions": 0, "times_redeemed": 0, "valid": false, "created_at": "2026-06-15T14:30:00Z", "test_mode": false } ] } }, "CouponBody_for_CreateCouponRequest": { "description": "An envelope wrapping a single coupon object.", "type": "object", "required": [ "coupon" ], "properties": { "coupon": { "description": "The coupon.", "$ref": "#/components/schemas/CreateCouponRequest" } }, "example": { "coupon": { "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "name": "Coupon", "amount_off": 100, "duration": "once", "percent_off": 10.0, "max_redemptions": 100, "metadata": { "key": "value" } } } }, "CouponBody_for_V1Coupon": { "description": "An envelope wrapping a single coupon object.", "type": "object", "required": [ "coupon" ], "properties": { "coupon": { "description": "The coupon.", "$ref": "#/components/schemas/V1Coupon" } }, "example": { "coupon": { "coupon_id": "fcoup_1234567890", "amount_off": 2500, "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "duration": "once", "duration_in_months": 0, "metadata": { "order_id": "8842", "channel": "shopify" }, "name": "Example", "percent_off": 0.0, "max_redemptions": 0, "times_redeemed": 0, "valid": false, "created_at": "2026-06-15T14:30:00Z", "test_mode": false } } }, "MultipleCustomersBody_for_Customer": { "description": "An envelope wrapping a list of customer objects.", "type": "object", "required": [ "customers" ], "properties": { "customers": { "description": "The list of customers.", "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } }, "example": { "customers": [ { "customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D", "owner_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false } ] } }, "CustomerBody_for_CreateCustomerRequest": { "description": "An envelope wrapping a single customer object.", "type": "object", "required": [ "customer" ], "properties": { "customer": { "description": "The customer.", "$ref": "#/components/schemas/CreateCustomerRequest" } }, "example": { "customer": { "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": "{\"key\": \"value\"}" } } }, "CreateCustomerRequest": { "description": "Parameters for creating a customer. If a customer with the same email already exists, that customer is updated with these values instead of a new one being created.", "type": "object", "required": [ "email", "first_name", "last_name", "phone" ], "properties": { "first_name": { "description": "The customer's first name.", "type": "string", "example": "John" }, "last_name": { "description": "The customer's last name.", "type": "string", "example": "Doe" }, "email": { "description": "The customer's email address. Used as the natural key: a request matching an existing customer's email updates that customer rather than creating a new one.", "type": "string", "format": "email", "example": "joh.doe@example.com" }, "phone": { "description": "The customer's phone number. Must be a valid phone number; it is normalized to E.164 format before being stored.", "type": "string", "format": "phone", "example": "+15555555555" }, "employer": { "description": "The customer's employer.", "type": [ "string", "null" ], "example": "Flex" }, "shipping": { "description": "The customer's shipping address.", "anyOf": [ { "$ref": "#/components/schemas/CreateShippingAddress" }, { "type": "null" } ] }, "checkout_session_id": { "description": "ID of a CheckoutSession to associate with this customer. When provided, the checkout session's customer (and its shipping details, if a shipping address is supplied) is updated to reference this customer.", "type": [ "string", "null" ], "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "metadata": { "description": "Set of key-value pairs you can attach to the customer for storing additional structured information.", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": "{\"key\": \"value\"}" } }, "example": { "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": "{\"key\": \"value\"}" } }, "CreateShippingAddress": { "description": "Parameters for supplying a shipping address when creating an object that ships to a customer.", "type": "object", "properties": { "line1": { "description": "The first line of the street address (e.g., street number and name).", "type": [ "string", "null" ], "example": "123 Main St" }, "line2": { "description": "The second line of the street address (e.g., apartment, suite, or unit).", "type": [ "string", "null" ], "example": "Suite 100" }, "city": { "description": "City, district, suburb, town, or village.", "type": [ "string", "null" ], "example": "San Francisco" }, "state": { "description": "State, county, province, or region.", "type": [ "string", "null" ], "example": "CA" }, "postal_code": { "description": "ZIP or postal code.", "type": [ "string", "null" ], "example": "94107" }, "country": { "description": "Two-letter country code (ISO 3166-1 alpha-2, e.g., `US`).", "type": [ "string", "null" ], "example": "US" } }, "example": { "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" } }, "CustomerBody_for_Customer": { "description": "An envelope wrapping a single customer object.", "type": "object", "required": [ "customer" ], "properties": { "customer": { "description": "The customer.", "$ref": "#/components/schemas/Customer" } }, "example": { "customer": { "customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D", "owner_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false } } }, "CustomerBody_for_UpdateCustomerRequest": { "description": "An envelope wrapping a single customer object.", "type": "object", "required": [ "customer" ], "properties": { "customer": { "description": "The customer.", "$ref": "#/components/schemas/UpdateCustomerRequest" } }, "example": { "customer": { "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "metadata": "{\"key\": \"value\"}" } } }, "UpdateCustomerRequest": { "description": "Parameters for updating a customer. Only the fields you provide are changed; omitted fields are left unchanged.", "type": "object", "required": [ "email" ], "properties": { "first_name": { "description": "The customer's first name. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "John" }, "last_name": { "description": "The customer's last name. Omit to leave unchanged.", "type": [ "string", "null" ], "example": "Doe" }, "email": { "description": "The customer's email address. Omit to leave unchanged.", "type": "string", "format": "email", "example": "joh.doe@example.com" }, "phone": { "description": "The customer's phone number. Must be a valid phone number; it is normalized to E.164 format before being stored. Omit to leave unchanged.", "type": [ "string", "null" ], "format": "phone", "example": "+15555555555" }, "employer": { "description": "The customer's employer.", "type": [ "string", "null" ], "example": "Flex" }, "shipping": { "description": "The customer's shipping address. When provided, a new shipping address is created and attached to the customer. Omit to leave unchanged.", "anyOf": [ { "$ref": "#/components/schemas/CreateShippingAddress" }, { "type": "null" } ] }, "metadata": { "description": "Set of key-value pairs you can attach to the customer for storing additional structured information. Omit to leave unchanged.", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": "{\"key\": \"value\"}" } }, "example": { "first_name": "John", "last_name": "Doe", "email": "joh.doe@example.com", "phone": "+15555555555", "employer": "Flex", "shipping": { "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US" }, "metadata": "{\"key\": \"value\"}" } }, "CustomerBody_for_DeletedCustomerResponse": { "description": "An envelope wrapping a single customer object.", "type": "object", "required": [ "customer" ], "properties": { "customer": { "description": "The customer.", "$ref": "#/components/schemas/DeletedCustomerResponse" } }, "example": { "customer": { "customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D", "deleted": true } } }, "DeletedCustomerResponse": { "description": "The response returned when a customer is deleted, confirming the deletion.", "type": "object", "required": [ "customer_id", "deleted" ], "properties": { "customer_id": { "description": "ID of the deleted Customer.", "type": "string", "example": "fcus_01HACM7FZ1084XB1GB6053VM0D" }, "deleted": { "description": "Always `true`, confirming the customer was deleted.", "type": "boolean", "example": true } }, "example": { "customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D", "deleted": true } }, "MultiplePaymentMethodsBody_for_V1PaymentMethod": { "description": "An envelope wrapping a list of payment method objects.", "type": "object", "required": [ "payment_methods" ], "properties": { "payment_methods": { "description": "The list of payment methods.", "type": "array", "items": { "$ref": "#/components/schemas/V1PaymentMethod" } } }, "example": { "payment_methods": [ { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "billing_details": { "address": { "city": "San Francisco", "country": "US", "line1": "123 Main St", "line2": "Suite 100", "postal_code": "94107", "state": "CA" }, "email": "john.doe@example.com", "name": "Example", "phone": "+14155550142" }, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "card": { "brand": "american_express", "country": "example_value", "exp_month": 12, "exp_year": 2027, "funding": "credit", "last4": "example_value" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "off_session": false } ] } }, "V1PaymentMethod": { "description": "A PaymentMethod object represents a customer's payment instrument (such as a card) that can be used to collect payments. Attach it to a Customer to reuse it across checkout sessions, invoices, and subscriptions.", "type": "object", "required": [ "billing_details", "card", "created_at", "customer", "off_session", "payment_method_id", "test_mode" ], "properties": { "payment_method_id": { "description": "The ID of the PaymentMethod.", "type": "string", "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "billing_details": { "description": "Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.", "$ref": "#/components/schemas/BillingDetails" }, "customer": { "description": "The customer this payment method is attached to. Returned as the customer ID by default; expandable to the full Customer object.", "$ref": "#/components/schemas/Expandable_for_Customer" }, "metadata": { "description": "Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.", "type": [ "object", "null" ], "additionalProperties": { "type": "object" }, "example": { "order_id": "8842", "channel": "shopify" } }, "card": { "description": "User card details.", "$ref": "#/components/schemas/V1Card" }, "created_at": { "description": "Time at which the object was created. ISO 8601 format.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "test_mode": { "description": "Whether this PaymentMethod is in test mode.", "type": "boolean", "example": false }, "off_session": { "description": "Whether this PaymentMethod is valid for off_session (customer not present) purchase flows.", "type": "boolean", "example": false } }, "example": { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "billing_details": { "address": { "city": "San Francisco", "country": "US", "line1": "123 Main St", "line2": "Suite 100", "postal_code": "94107", "state": "CA" }, "email": "john.doe@example.com", "name": "Example", "phone": "+14155550142" }, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "card": { "brand": "american_express", "country": "example_value", "exp_month": 12, "exp_year": 2027, "funding": "credit", "last4": "example_value" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "off_session": false } }, "V1Card": { "description": "The card backing a PaymentMethod, as returned by the public API: brand, country, expiration, funding type, and the last four digits.", "type": "object", "required": [ "brand", "country", "exp_month", "exp_year", "funding", "last4" ], "properties": { "brand": { "description": "The brand of the card.", "$ref": "#/components/schemas/CardBrand" }, "country": { "description": "Two-letter ISO country code of the card's issuing country (e.g., `US`).", "type": "string", "example": "example_value" }, "exp_month": { "description": "The card's expiration month.", "type": "integer", "format": "int32", "example": 12, "minimum": -128.0, "maximum": 127.0 }, "exp_year": { "description": "The card's expiration year.", "type": "integer", "format": "int32", "example": 2027, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "funding": { "description": "The funding type of the card.", "$ref": "#/components/schemas/CardFunding" }, "last4": { "description": "The last four digits of the card.", "type": "string", "example": "example_value" } }, "example": { "brand": "american_express", "country": "example_value", "exp_month": 12, "exp_year": 2027, "funding": "credit", "last4": "example_value" } }, "PaymentMethodBody_for_V1PaymentMethod": { "description": "An envelope wrapping a single payment method object.", "type": "object", "required": [ "payment_method" ], "properties": { "payment_method": { "description": "The payment method.", "$ref": "#/components/schemas/V1PaymentMethod" } }, "example": { "payment_method": { "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "billing_details": { "address": { "city": "San Francisco", "country": "US", "line1": "123 Main St", "line2": "Suite 100", "postal_code": "94107", "state": "CA" }, "email": "john.doe@example.com", "name": "Example", "phone": "+14155550142" }, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "card": { "brand": "american_express", "country": "example_value", "exp_month": 12, "exp_year": 2027, "funding": "credit", "last4": "example_value" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "off_session": false } } }, "MultipleExportsBody_for_Export": { "description": "An envelope wrapping a list of export objects.", "type": "object", "required": [ "export" ], "properties": { "export": { "description": "The list of exports.", "type": "array", "items": { "$ref": "#/components/schemas/Export" } } }, "example": { "export": [ { "export_id": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "type": "product", "status": "created", "created_at": "2026-06-15T14:30:00Z", "started_at": "2026-06-15T14:30:00Z", "completed_at": "2026-06-15T14:30:00Z", "metadata": { "order_id": "8842", "channel": "shopify" }, "filters": { "payment": { "limit": 0, "status": "canceled", "starting_after": "string", "ending_before": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "limit": 0, "offset": 0, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string", "start_date": "string", "end_date": "string" }, "subscription": { "limit": 0, "offset": 0, "start_date": "string", "end_date": "string" }, "customer": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "product": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "charge_reconciliation": { "start_date": "string", "end_date": "string" }, "payout": { "start_date": "string", "end_date": "string" }, "dispute": { "start_date": "string", "end_date": "string" }, "line_item": { "start_date": "string", "end_date": "string" }, "line_item_revenue": { "start_date": "string", "end_date": "string" }, "balance_activity": { "start_date": "string", "end_date": "string" } }, "test_mode": false } ] } }, "ExportBody_for_CreateExportRequest": { "description": "An envelope wrapping a single export object.", "type": "object", "required": [ "export" ], "properties": { "export": { "description": "The Export object.", "$ref": "#/components/schemas/CreateExportRequest" } }, "example": { "export": { "description": "Premium SPF 50 mineral sunscreen", "filters": { "payment": { "limit": 0, "status": "canceled", "starting_after": "string", "ending_before": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "limit": 0, "offset": 0, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string", "start_date": "string", "end_date": "string" }, "subscription": { "limit": 0, "offset": 0, "start_date": "string", "end_date": "string" }, "customer": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "product": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "charge_reconciliation": { "start_date": "string", "end_date": "string" }, "payout": { "start_date": "string", "end_date": "string" }, "dispute": { "start_date": "string", "end_date": "string" }, "line_item": { "start_date": "string", "end_date": "string" }, "line_item_revenue": { "start_date": "string", "end_date": "string" }, "balance_activity": { "start_date": "string", "end_date": "string" } }, "metadata": { "order_id": "8842", "channel": "shopify" }, "type": "product" } } }, "CreateExportRequest": { "description": "Parameters for creating an export.", "type": "object", "required": [ "type" ], "properties": { "description": { "description": "An arbitrary description to attach to the export for your own reference.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" }, "filters": { "description": "Criteria that restrict which records the export includes. The filter variant must match `type`. When omitted, all of your records are exported.", "anyOf": [ { "$ref": "#/components/schemas/Filters" }, { "type": "null" } ] }, "metadata": { "description": "Set of key-value pairs to attach to the export for storing additional structured information.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "type": { "description": "The kind of data to export.", "$ref": "#/components/schemas/ExportType" } }, "example": { "description": "Premium SPF 50 mineral sunscreen", "filters": { "payment": { "limit": 0, "status": "canceled", "starting_after": "string", "ending_before": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "limit": 0, "offset": 0, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string", "start_date": "string", "end_date": "string" }, "subscription": { "limit": 0, "offset": 0, "start_date": "string", "end_date": "string" }, "customer": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "product": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "charge_reconciliation": { "start_date": "string", "end_date": "string" }, "payout": { "start_date": "string", "end_date": "string" }, "dispute": { "start_date": "string", "end_date": "string" }, "line_item": { "start_date": "string", "end_date": "string" }, "line_item_revenue": { "start_date": "string", "end_date": "string" }, "balance_activity": { "start_date": "string", "end_date": "string" } }, "metadata": { "order_id": "8842", "channel": "shopify" }, "type": "product" } }, "ExportBody_for_Export": { "description": "An envelope wrapping a single export object.", "type": "object", "required": [ "export" ], "properties": { "export": { "description": "The Export object.", "$ref": "#/components/schemas/Export" } }, "example": { "export": { "export_id": "fxprt_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "type": "product", "status": "created", "created_at": "2026-06-15T14:30:00Z", "started_at": "2026-06-15T14:30:00Z", "completed_at": "2026-06-15T14:30:00Z", "metadata": { "order_id": "8842", "channel": "shopify" }, "filters": { "payment": { "limit": 0, "status": "canceled", "starting_after": "string", "ending_before": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "limit": 0, "offset": 0, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string", "start_date": "string", "end_date": "string" }, "subscription": { "limit": 0, "offset": 0, "start_date": "string", "end_date": "string" }, "customer": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "product": { "limit": 0, "offset": 0, "starting_after": "string", "ending_before": "string" }, "charge_reconciliation": { "start_date": "string", "end_date": "string" }, "payout": { "start_date": "string", "end_date": "string" }, "dispute": { "start_date": "string", "end_date": "string" }, "line_item": { "start_date": "string", "end_date": "string" }, "line_item_revenue": { "start_date": "string", "end_date": "string" }, "balance_activity": { "start_date": "string", "end_date": "string" } }, "test_mode": false } } }, "PresignedUrlBody_for_String": { "description": "An envelope wrapping a presigned download URL for an export's generated file.", "type": "object", "required": [ "url" ], "properties": { "url": { "description": "A temporary, presigned URL for downloading the export's generated file. Expires after a short period.", "type": "string" } }, "example": { "url": "string" } }, "MultipleInvoicesBody_for_Invoice": { "description": "An envelope wrapping a list of invoice objects.", "type": "object", "required": [ "invoices" ], "properties": { "invoices": { "description": "The list of invoices.", "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } }, "example": { "invoices": [ { "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "total": 2500, "amount_due": 2500, "amount_paid": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "period_end": "string", "period_start": "string", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "paid_at": "string", "status": "draft", "collection_method": "charge_automatically", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "backup_charge_status": "pending" } ] } }, "InvoiceBody_for_Invoice": { "description": "An envelope wrapping a single invoice object.", "type": "object", "required": [ "invoice" ], "properties": { "invoice": { "description": "The invoice object.", "$ref": "#/components/schemas/Invoice" } }, "example": { "invoice": { "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "total": 2500, "amount_due": 2500, "amount_paid": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "period_end": "string", "period_start": "string", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "paid_at": "string", "status": "draft", "collection_method": "charge_automatically", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "backup_charge_status": "pending" } } }, "ComponentCategory": { "type": "string", "enum": [ "base", "protein", "topping", "premium", "dressing" ], "x-ms-enum": { "name": "ComponentCategory", "modelAsString": false, "values": [ { "value": "base", "name": "Base", "description": "The bowl's base — a grain, green or other foundation." }, { "value": "protein", "name": "Protein", "description": "A protein." }, { "value": "topping", "name": "Topping", "description": "A standard topping." }, { "value": "premium", "name": "Premium", "description": "A premium topping." }, { "value": "dressing", "name": "Dressing", "description": "A dressing. The one category the eligibility engine gates differently." } ] }, "description": "A component's menu category.\n\nAn enum on the way in and a plain string on the way out, deliberately. `product_component_nutrition.category` is `text` with no CHECK constraint (per the company convention that the backend owns validation), so a row written by a backfill or by raw SQL can hold a value outside this set. Being strict on write keeps bad values out; being tolerant on read means such a row is still retrievable instead of 500ing on serialization.\n\nThe variants mirror [`flex_core::product_metadata::VALID_CATEGORIES`], which is what the write path actually validates against; `test_component_category_matches_flex_core` pins the two together so a category added there cannot be silently unreachable through the API.\n\n- `base`: The bowl's base — a grain, green or other foundation.\n- `protein`: A protein.\n- `topping`: A standard topping.\n- `premium`: A premium topping.\n- `dressing`: A dressing. The one category the eligibility engine gates differently.", "example": "base" }, "MultipleProductComponentsBody_for_V1ProductComponent": { "description": "An envelope wrapping a list of product component objects.", "type": "object", "required": [ "product_components" ], "properties": { "product_components": { "description": "The list of product components.", "type": "array", "items": { "$ref": "#/components/schemas/V1ProductComponent" } } }, "example": { "product_components": [ { "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "component_nutrition_id": "fcn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "string", "shared": true, "test_mode": true, "category": "string", "serving_size_g": 0.0, "nutrition": { "calories": 0.0, "total_fat_g": 0.0, "saturated_fat_g": 0.0, "trans_fat_g": 0.0, "carbohydrate_g": 0.0, "fiber_g": 0.0, "protein_g": 0.0, "sodium_mg": 0.0, "added_sugar_g": 0.0 }, "vegan": true, "gluten_free": true, "canonical_food_key": "string", "client_reference_id": "string", "metadata": {}, "created_at": "string", "updated_at": "string" } ] } }, "V1ProductComponent": { "description": "A component together with the nutrition this partner has recorded for it. Every nutrient value is per 100 g.", "type": "object", "required": [ "category", "component_id", "component_nutrition_id", "created_at", "gluten_free", "name", "nutrition", "shared", "test_mode", "vegan" ], "properties": { "component_id": { "description": "The component's unique identifier. This is the id `component_items` on `PATCH /v1/products/{id}` accepts.", "type": "string", "example": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "component_nutrition_id": { "description": "The identifier of the nutrition record holding your figures for this component.", "type": "string", "example": "fcn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "name": { "description": "The component's name, normalized to lowercase.", "type": "string" }, "shared": { "description": "Whether the underlying name row is shared across partners rather than owned by you. `true` for everything registered through this endpoint today, which is why the name cannot be changed.", "type": "boolean" }, "test_mode": { "description": "Whether these figures belong to test mode.", "type": "boolean" }, "category": { "description": "The component's menu category.", "type": "string" }, "serving_size_g": { "description": "The standard portion, in grams. Not a per-100 g nutrient.", "type": [ "number", "null" ], "format": "double" }, "nutrition": { "description": "Nutrient values, per 100 g.", "$ref": "#/components/schemas/ComponentNutritionValues" }, "vegan": { "description": "Whether the component is vegan.", "type": "boolean" }, "gluten_free": { "description": "Whether the component is gluten-free.", "type": "boolean" }, "canonical_food_key": { "description": "The join key into Flex's national price book, or `null` if not yet mapped.", "type": [ "string", "null" ] }, "client_reference_id": { "description": "Your own identifier for this ingredient, or `null` if you did not set one.", "type": [ "string", "null" ] }, "metadata": { "description": "The key-value pairs you stored on this component, or `null` if none.", "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "created_at": { "description": "When these figures were first recorded.", "$ref": "#/components/schemas/Timestamptz" }, "updated_at": { "description": "When these figures were last changed, or `null` if never.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ] } }, "example": { "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "component_nutrition_id": "fcn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "string", "shared": true, "test_mode": true, "category": "string", "serving_size_g": 0.0, "nutrition": { "calories": 0.0, "total_fat_g": 0.0, "saturated_fat_g": 0.0, "trans_fat_g": 0.0, "carbohydrate_g": 0.0, "fiber_g": 0.0, "protein_g": 0.0, "sodium_mg": 0.0, "added_sugar_g": 0.0 }, "vegan": true, "gluten_free": true, "canonical_food_key": "string", "client_reference_id": "string", "metadata": {}, "created_at": "string", "updated_at": "string" } }, "ComponentNutritionValues": { "description": "Nutrient values for one component. **Every value is per 100 g of the component**, never per serving — see `nutrition_basis` on the write paths for how per-serving figures are converted on the way in.\n\nA `null` means *not supplied*, which is distinct from `0`: the eligibility engine treats a missing nutrient as a reason it cannot produce a split, whereas a zero is a real measurement.", "type": "object", "properties": { "calories": { "description": "Energy, kcal per 100 g.", "type": [ "number", "null" ], "format": "double" }, "total_fat_g": { "description": "Total fat, g per 100 g. Informational — the eligibility gate uses saturated fat.", "type": [ "number", "null" ], "format": "double" }, "saturated_fat_g": { "description": "Saturated fat, g per 100 g. This is the fat the eligibility gate uses.", "type": [ "number", "null" ], "format": "double" }, "trans_fat_g": { "description": "Trans fat, g per 100 g.", "type": [ "number", "null" ], "format": "double" }, "carbohydrate_g": { "description": "Carbohydrate, g per 100 g.", "type": [ "number", "null" ], "format": "double" }, "fiber_g": { "description": "Fiber, g per 100 g.", "type": [ "number", "null" ], "format": "double" }, "protein_g": { "description": "Protein, g per 100 g.", "type": [ "number", "null" ], "format": "double" }, "sodium_mg": { "description": "Sodium, mg per 100 g.", "type": [ "number", "null" ], "format": "double" }, "added_sugar_g": { "description": "Added sugar, g per 100 g.", "type": [ "number", "null" ], "format": "double" } }, "example": { "calories": 0.0, "total_fat_g": 0.0, "saturated_fat_g": 0.0, "trans_fat_g": 0.0, "carbohydrate_g": 0.0, "fiber_g": 0.0, "protein_g": 0.0, "sodium_mg": 0.0, "added_sugar_g": 0.0 } }, "ProductComponentBody_for_CreateProductComponentRequest": { "description": "An envelope wrapping a single product component object.", "type": "object", "required": [ "product_component" ], "properties": { "product_component": { "description": "The product component object.", "$ref": "#/components/schemas/CreateProductComponentRequest" } }, "example": { "product_component": { "name": "string", "category": "base", "nutrition_basis": "per_100g", "serving_size_g": 0.0, "nutrition": { "calories": 0.0, "total_fat_g": 0.0, "saturated_fat_g": 0.0, "trans_fat_g": 0.0, "carbohydrate_g": 0.0, "fiber_g": 0.0, "protein_g": 0.0, "sodium_mg": 0.0, "added_sugar_g": 0.0 }, "vegan": true, "gluten_free": true, "canonical_food_key": "string", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" } } } }, "CreateProductComponentRequest": { "description": "Parameters for registering a product component.\n\nThe name is matched case-insensitively against a shared name table, so registering a name another partner already registered returns that same `component_id` with your own nutrition attached — it does not fail, and it does not expose their figures.", "type": "object", "required": [ "category", "name" ], "properties": { "name": { "description": "The component's name, e.g. `\"kale\"`. Trimmed and lowercased before storage.", "type": "string" }, "category": { "description": "The component's menu category.", "$ref": "#/components/schemas/ComponentCategory" }, "nutrition_basis": { "description": "The basis `nutrition` is expressed on. Defaults to `per_100g`.", "anyOf": [ { "$ref": "#/components/schemas/NutritionBasis" }, { "type": "null" } ] }, "serving_size_g": { "description": "The standard portion of this component, in grams. Not a per-100 g nutrient: it is never rescaled, and it is what `as_served` figures are converted by.", "type": [ "number", "null" ], "format": "double" }, "nutrition": { "description": "Nutrient values. Omit any you do not have; a missing value stays \"not supplied\" rather than becoming zero.", "anyOf": [ { "$ref": "#/components/schemas/ComponentNutritionValues" }, { "type": "null" } ] }, "vegan": { "description": "Whether the component is vegan. Defaults to `false`.", "type": [ "boolean", "null" ] }, "gluten_free": { "description": "Whether the component is gluten-free. Defaults to `false`.", "type": [ "boolean", "null" ] }, "canonical_food_key": { "description": "The join key into Flex's national price book. Optional here — the eligibility engine, not this endpoint, is what requires it for a non-dressing component.\n\nStored normalized: lowercased, trimmed, and with hyphens folded into underscores, so `Goat-Cheese` is saved and returned as `goat_cheese`. The price book is snake_case throughout, and this is what makes your spelling and ours the same key.", "type": [ "string", "null" ] }, "client_reference_id": { "description": "Your own identifier for this ingredient — a menu item id, POS SKU, or whatever your catalogue keys on.\n\nUnique within your account and mode, so a re-sync that reuses one is a `409` rather than a second component pointing at the same ingredient. That is what makes it usable as a sync key: register once, then look the component up with `GET /v1/product_components?client_reference_id=…` instead of paging your whole catalogue. Another account may use the same value for their own ingredient, and so may you in your other mode.", "type": [ "string", "null" ], "example": "example_value" }, "metadata": { "description": "Key-value pairs to store on the component. Yours to read back; Flex does not interpret them.", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": { "order_id": "8842", "channel": "shopify" } } }, "example": { "name": "string", "category": "base", "nutrition_basis": "per_100g", "serving_size_g": 0.0, "nutrition": { "calories": 0.0, "total_fat_g": 0.0, "saturated_fat_g": 0.0, "trans_fat_g": 0.0, "carbohydrate_g": 0.0, "fiber_g": 0.0, "protein_g": 0.0, "sodium_mg": 0.0, "added_sugar_g": 0.0 }, "vegan": true, "gluten_free": true, "canonical_food_key": "string", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" } } }, "NutritionBasis": { "type": "string", "enum": [ "per_100g", "as_served" ], "x-ms-enum": { "name": "NutritionBasis", "modelAsString": false, "values": [ { "value": "per_100g", "name": "Per100g", "description": "The values are already per 100 g. The default." }, { "value": "as_served", "name": "AsServed", "description": "The values describe one `serving_size_g` portion as served, and are converted to per 100 g before being stored." } ] }, "description": "The basis the supplied nutrient values are expressed on.\n\nStorage is always per 100 g; this only describes the *request*. `as_served` requires a usable `serving_size_g` to convert by.\n\n- `per_100g`: The values are already per 100 g. The default.\n- `as_served`: The values describe one `serving_size_g` portion as served, and are converted to per 100 g before being stored.", "example": "per_100g" }, "ProductComponentBody_for_V1ProductComponent": { "description": "An envelope wrapping a single product component object.", "type": "object", "required": [ "product_component" ], "properties": { "product_component": { "description": "The product component object.", "$ref": "#/components/schemas/V1ProductComponent" } }, "example": { "product_component": { "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "component_nutrition_id": "fcn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "string", "shared": true, "test_mode": true, "category": "string", "serving_size_g": 0.0, "nutrition": { "calories": 0.0, "total_fat_g": 0.0, "saturated_fat_g": 0.0, "trans_fat_g": 0.0, "carbohydrate_g": 0.0, "fiber_g": 0.0, "protein_g": 0.0, "sodium_mg": 0.0, "added_sugar_g": 0.0 }, "vegan": true, "gluten_free": true, "canonical_food_key": "string", "client_reference_id": "string", "metadata": {}, "created_at": "string", "updated_at": "string" } } }, "ProductComponentBody_for_UpdateProductComponentRequest": { "description": "An envelope wrapping a single product component object.", "type": "object", "required": [ "product_component" ], "properties": { "product_component": { "description": "The product component object.", "$ref": "#/components/schemas/UpdateProductComponentRequest" } }, "example": { "product_component": { "category": "base", "nutrition_basis": "per_100g", "serving_size_g": 0.0, "nutrition": { "calories": 0.0, "total_fat_g": 0.0, "saturated_fat_g": 0.0, "trans_fat_g": 0.0, "carbohydrate_g": 0.0, "fiber_g": 0.0, "protein_g": 0.0, "sodium_mg": 0.0, "added_sugar_g": 0.0 }, "vegan": true, "gluten_free": true, "canonical_food_key": "string", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "clear": [ "serving_size_g" ] } } }, "UpdateProductComponentRequest": { "description": "Parameters for updating a product component. Only the fields you supply are changed; omitted fields are left unchanged.\n\nThere is no `name`: the underlying name row is shared with every other partner that registered the same ingredient, so a rename here would edit their data. Register a new component instead.\n\nTo reset a value to \"not supplied\", list it in `clear` — omitting it means \"leave alone\", so omission cannot express erasure. Clearing a field and setting it in the same request is rejected.", "type": "object", "properties": { "category": { "description": "The component's menu category.", "anyOf": [ { "$ref": "#/components/schemas/ComponentCategory" }, { "type": "null" } ] }, "nutrition_basis": { "description": "The basis the supplied `nutrition` values are expressed on. Defaults to `per_100g`. `as_served` converts by `serving_size_g` — the one in this request if present, otherwise the stored one.", "anyOf": [ { "$ref": "#/components/schemas/NutritionBasis" }, { "type": "null" } ] }, "serving_size_g": { "description": "The standard portion of this component, in grams.", "type": [ "number", "null" ], "format": "double" }, "nutrition": { "description": "Nutrient values to change. Omitted nutrients are left unchanged.", "anyOf": [ { "$ref": "#/components/schemas/ComponentNutritionValues" }, { "type": "null" } ] }, "vegan": { "description": "Whether the component is vegan.", "type": [ "boolean", "null" ] }, "gluten_free": { "description": "Whether the component is gluten-free.", "type": [ "boolean", "null" ] }, "canonical_food_key": { "description": "The join key into Flex's national price book. Normalized the same way as on create: lowercased, trimmed, hyphens folded into underscores.", "type": [ "string", "null" ] }, "client_reference_id": { "description": "Your own identifier for this ingredient. Still unique within your account and mode, so moving one onto a component that would collide with another of yours is a `409`.", "type": [ "string", "null" ], "example": "example_value" }, "metadata": { "description": "Key-value pairs to **merge** into the stored metadata: keys you send are added or overwritten, keys you omit are left alone. A merge cannot remove a key, so erasing the object means `clear: [\"metadata\"]`.", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": { "order_id": "8842", "channel": "shopify" } }, "clear": { "description": "Fields to reset to \"not supplied\".", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ClearableField" } } }, "example": { "category": "base", "nutrition_basis": "per_100g", "serving_size_g": 0.0, "nutrition": { "calories": 0.0, "total_fat_g": 0.0, "saturated_fat_g": 0.0, "trans_fat_g": 0.0, "carbohydrate_g": 0.0, "fiber_g": 0.0, "protein_g": 0.0, "sodium_mg": 0.0, "added_sugar_g": 0.0 }, "vegan": true, "gluten_free": true, "canonical_food_key": "string", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "clear": [ "serving_size_g" ] } }, "ClearableField": { "description": "A nullable field an update may reset to \"not supplied\".\n\n`category`, `vegan` and `gluten_free` are absent on purpose: they are never null in storage, so they can be changed but not cleared.", "oneOf": [ { "type": "string", "enum": [ "serving_size_g", "calories", "total_fat_g", "saturated_fat_g", "trans_fat_g", "carbohydrate_g", "fiber_g", "protein_g", "sodium_mg", "added_sugar_g", "canonical_food_key", "client_reference_id" ] }, { "description": "Removes every metadata key. An update *merges* the object it is given, so this is the only way to take a key back off a component.", "type": "string", "enum": [ "metadata" ] } ], "example": "serving_size_g" }, "MultipleProductsBody_for_Product": { "description": "An envelope wrapping a list of product objects.", "type": "object", "required": [ "products" ], "properties": { "products": { "description": "The list of products.", "type": "array", "items": { "$ref": "#/components/schemas/Product" } } }, "example": { "products": [ { "product_id": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "document_description": "string", "receipt_description": "string", "created_at": "2026-06-15T14:30:00Z", "visit_type": "cbtSleep", "active": false, "upc_code": "string", "gtin": "string", "reference_gtin": "string", "hsa_fsa_eligibility": "not_eligible", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ] } }, "ProductBody_for_CreateProductRequest": { "description": "An envelope wrapping a single product object.", "type": "object", "required": [ "product" ], "properties": { "product": { "description": "The product object.", "$ref": "#/components/schemas/CreateProductRequest" } }, "example": { "product": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } } }, "ProductBody_for_Product": { "description": "An envelope wrapping a single product object.", "type": "object", "required": [ "product" ], "properties": { "product": { "description": "The product object.", "$ref": "#/components/schemas/Product" } }, "example": { "product": { "product_id": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "document_description": "string", "receipt_description": "string", "created_at": "2026-06-15T14:30:00Z", "visit_type": "cbtSleep", "active": false, "upc_code": "string", "gtin": "string", "reference_gtin": "string", "hsa_fsa_eligibility": "not_eligible", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } }, "ProcessingStatusBody": { "description": "Catalog-wide eligibility processing status for the authenticated account.", "type": "object", "required": [ "pending_classification", "pending_classification_capped" ], "properties": { "pending_classification": { "description": "How many active products are still awaiting automatic HSA/FSA eligibility classification. Capped (see `pending_classification_capped`); the frontend derives any time estimate from this count itself.", "type": "integer", "format": "int64", "example": 142, "minimum": -9007199254740991.0, "maximum": 9007199254740991.0 }, "pending_classification_capped": { "description": "True when `pending_classification` hit its ceiling — the true number is at least that. Clients should render e.g. \"10,000+\".", "type": "boolean", "example": false } }, "example": { "pending_classification": 142, "pending_classification_capped": false } }, "ProductBody_for_UpdateProductRequest": { "description": "An envelope wrapping a single product object.", "type": "object", "required": [ "product" ], "properties": { "product": { "description": "The product object.", "$ref": "#/components/schemas/UpdateProductRequest" } }, "example": { "product": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "active": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "categories": [ "string" ], "component_items": [ { "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ] } } }, "UpdateProductRequest": { "description": "Parameters for updating a product. Only the fields you supply are changed; omitted fields are left unchanged. Updates never re-run Flex's automatic HSA/FSA eligibility determination — eligibility is set when the product is created and afterwards only changes through review.", "type": "object", "properties": { "name": { "description": "The product's name, meant to be displayed to the customer.", "type": [ "string", "null" ], "example": "Example" }, "description": { "description": "The product's description, a short blurb meant to be displayed to the customer.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" }, "upc_code": { "description": "The product's UPC code. If provided, this will be used to check whether the product is on the eligible product list.", "type": [ "string", "null" ], "example": "example_value" }, "gtin": { "description": "The product's GTIN. If provided, this will be used to check whether the product is on the eligible product list.", "type": [ "string", "null" ], "example": "example_value" }, "reference_gtin": { "description": "If the product is HSA/FSA eligible through private label, this should be provided.", "type": [ "string", "null" ], "example": "example_value" }, "url": { "description": "A URL of a publicly-accessible image of the product.", "type": [ "string", "null" ], "example": "https://example.com" }, "active": { "description": "Whether the product can be used for new purchases. Set to `false` to archive the product.", "type": [ "boolean", "null" ], "example": false }, "metadata": { "description": "Set of key-value pairs that you can attach to a product. This can be useful for storing additional information about the product in a structured format.", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": { "order_id": "8842", "channel": "shopify" } }, "categories": { "description": "Product categories (e.g., \"Vitamins\", \"First Aid\"). If provided, replaces all existing categories. Pass an empty array `[]` to remove all categories. Omit this field to preserve existing categories.", "type": [ "array", "null" ], "items": { "type": "string" } }, "component_items": { "description": "The components (ingredients) this product is made of, as `fcomp_` ids from `/v1/product_components`.\n\nIf provided, **replaces** the product's entire component list: an id you omit is detached. Pass an empty array `[]` to detach them all, and omit the field to leave the list alone.\n\nThis is the only way to change a product's components after it exists — `components` on product-create takes names and is create-only.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ComponentItem" } } }, "example": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "active": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "categories": [ "string" ], "component_items": [ { "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ] } }, "ComponentItem": { "description": "One component attached to a product.\n\nAn id and nothing else. There is deliberately **no quantity**: how much of an ingredient a particular order contains is per-order data and arrives on the checkout line item, not on the product. A product's component list answers \"which ingredients\", and that is all it answers.", "type": "object", "required": [ "component_id" ], "properties": { "component_id": { "description": "The component's `fcomp_` identifier, from `/v1/product_components`. The component must be one of yours or one of Flex's shared components.", "type": "string", "example": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "example": { "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "MultiplePaymentIntentsBody_for_PaymentIntent": { "description": "An envelope wrapping a list of payment intent objects.", "type": "object", "required": [ "payment_intents" ], "properties": { "payment_intents": { "description": "The list of payment intents.", "type": "array", "items": { "$ref": "#/components/schemas/PaymentIntent" } } }, "example": { "payment_intents": [ { "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "amount_capturable": 2500, "amount_received": 2500, "application_fee_amount": 0, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "transfer_data": { "amount": 2500, "destination": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "status": "canceled", "latest_charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "capture_method": "automatic", "client_secret": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "transfer_group": "example_value", "payment_card_type": "primary", "letter_fee_amount": 0, "transaction_fee": 0, "last_payment_error": { "type": "string", "code": "string", "decline_code": "string", "message": "string", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } ] } }, "PaymentIntentBody_for_PaymentIntent": { "description": "An envelope wrapping a single payment intent object.", "type": "object", "required": [ "payment_intent" ], "properties": { "payment_intent": { "description": "The payment intent object.", "$ref": "#/components/schemas/PaymentIntent" } }, "example": { "payment_intent": { "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "amount_capturable": 2500, "amount_received": 2500, "application_fee_amount": 0, "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "transfer_data": { "amount": 2500, "destination": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "status": "canceled", "latest_charge": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "capture_method": "automatic", "client_secret": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "transfer_group": "example_value", "payment_card_type": "primary", "letter_fee_amount": 0, "transaction_fee": 0, "last_payment_error": { "type": "string", "code": "string", "decline_code": "string", "message": "string", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } } }, "MultiplePaymentLinksBody_for_PaymentLink": { "description": "An envelope wrapping a list of payment link objects.", "type": "object", "required": [ "payment_links" ], "properties": { "payment_links": { "description": "The list of payment links.", "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" } } }, "example": { "payment_links": [ { "payment_link_id": "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "label": "Example", "active": false, "line_items": [ { "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } }, "quantity": 0, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "tax_rate": { "amount": 2500 }, "components": [ { "quantity": 1.0, "dressing_mode": "MIXED", "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string" } ] } ], "allow_promotion_codes": false, "shipping_address_collection": false, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "created_at": "2026-06-15T14:30:00Z", "payment_intent_data": { "capture_method": "automatic", "metadata": { "order_id": "8842", "channel": "shopify" } }, "after_completion": { "type": "redirect", "hosted_confirmation": { "custom_message": "Premium SPF 50 mineral sunscreen" }, "redirect": { "url": "https://example.com" } }, "origin": "shopify", "tax_rate": { "amount": 2500 }, "discounts": [ "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_future_use": "on_session", "test_mode": false } ] } }, "PaymentLink": { "description": "A Payment Link represents a shareable URL that generates a checkout session each time a customer opens it. Use it to sell products or collect a payment method without building your own checkout page.", "type": "object", "required": [ "active", "after_completion", "allow_promotion_codes", "created_at", "payment_link_id", "setup_future_use", "shipping_address_collection", "test_mode", "url" ], "properties": { "payment_link_id": { "description": "Unique identifier for the Payment Link", "type": "string", "example": "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "label": { "description": "Provided or generated label for the payment link.", "type": [ "string", "null" ], "example": "Example" }, "active": { "description": "Whether the payment link is currently active. If false, the link can no longer be used to generate checkout sessions and customers visiting the URL will be shown a not-found page.", "type": "boolean", "example": false }, "line_items": { "description": "The line items representing what is being sold.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/NewLineItem" } }, "allow_promotion_codes": { "description": "Whether promo codes are enabled", "type": "boolean", "example": false }, "shipping_address_collection": { "description": "Whether we want to collect shipping details at checkout time", "type": "boolean", "example": false }, "shipping_options": { "description": "The shipping rate options applied to the session.", "anyOf": [ { "$ref": "#/components/schemas/ShippingRateOptions" }, { "type": "null" } ] }, "metadata": { "description": "Metadata to attach to the payment session", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "url": { "description": "The public URL that can be shared with customers.", "type": "string", "example": "https://example.com" }, "created_at": { "description": "Time at which the object was created. ISO 8601 format.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "payment_intent_data": { "description": "Indicates the parameters to be passed to PaymentIntent creation during checkout.", "anyOf": [ { "$ref": "#/components/schemas/PaymentIntentData" }, { "type": "null" } ] }, "after_completion": { "description": "Behavior after the purchase is complete.", "$ref": "#/components/schemas/AfterCompletion" }, "origin": { "description": "Origin of the payment link", "anyOf": [ { "$ref": "#/components/schemas/CheckoutSessionOrigin" }, { "type": "null" } ] }, "tax_rate": { "description": "Session-level flat tax amount in cents (e.g., 500 = $5.00)", "anyOf": [ { "$ref": "#/components/schemas/TaxRate" }, { "type": "null" } ] }, "discounts": { "description": "Pre-stored coupon IDs to apply as discounts when generating checkout sessions", "type": [ "array", "null" ], "items": { "type": "string", "example": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "setup_future_use": { "description": "How the payment method is saved for future use on checkout sessions generated from this link. \"off_session\" keeps the card on file for future merchant-initiated charges; \"on_session\" requires the customer to be present for future payments.", "$ref": "#/components/schemas/FutureUse" }, "test_mode": { "description": "Whether the payment link was created in test mode", "type": "boolean", "example": false } }, "example": { "payment_link_id": "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "label": "Example", "active": false, "line_items": [ { "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } }, "quantity": 0, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "tax_rate": { "amount": 2500 }, "components": [ { "quantity": 1.0, "dressing_mode": "MIXED", "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string" } ] } ], "allow_promotion_codes": false, "shipping_address_collection": false, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "created_at": "2026-06-15T14:30:00Z", "payment_intent_data": { "capture_method": "automatic", "metadata": { "order_id": "8842", "channel": "shopify" } }, "after_completion": { "type": "redirect", "hosted_confirmation": { "custom_message": "Premium SPF 50 mineral sunscreen" }, "redirect": { "url": "https://example.com" } }, "origin": "shopify", "tax_rate": { "amount": 2500 }, "discounts": [ "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_future_use": "on_session", "test_mode": false } }, "PaymentIntentData": { "description": "Indicates the parameters to be passed to PaymentIntent creation during checkout", "type": "object", "required": [ "capture_method" ], "properties": { "capture_method": { "description": "How the PaymentIntent is captured: `automatic` captures the funds immediately after the customer authorizes the payment, `automatic_async` captures asynchronously, and `manual` authorizes the payment and requires a separate capture. Required when `payment_intent_data` is supplied; `automatic` is used when `payment_intent_data` is omitted entirely.", "$ref": "#/components/schemas/PaymentIntentCaptureMethod" }, "metadata": { "description": "Set of key-value pairs attached to the PaymentIntent created during checkout, for storing additional structured information.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } } }, "example": { "capture_method": "automatic", "metadata": { "order_id": "8842", "channel": "shopify" } } }, "AfterCompletion": { "description": "Configures what the customer sees after completing a checkout session generated from a payment link.", "type": "object", "required": [ "type" ], "properties": { "type": { "description": "The behavior to apply after completion: `hosted_confirmation` (Default) shows a Flex-hosted confirmation page, and `redirect` sends the customer to a URL you specify.", "$ref": "#/components/schemas/AfterCompletionType" }, "hosted_confirmation": { "description": "Configuration for the hosted confirmation page. Applies when `type` is `hosted_confirmation`; `null` otherwise.", "anyOf": [ { "$ref": "#/components/schemas/HostedConfirmation" }, { "type": "null" } ] }, "redirect": { "description": "Configuration for the post-completion redirect. Applies when `type` is `redirect`; `null` otherwise.", "anyOf": [ { "$ref": "#/components/schemas/Redirect" }, { "type": "null" } ] } }, "example": { "type": "redirect", "hosted_confirmation": { "custom_message": "Premium SPF 50 mineral sunscreen" }, "redirect": { "url": "https://example.com" } } }, "AfterCompletionType": { "description": "What happens after a payment link checkout completes: a redirect to your URL, or a Flex-hosted confirmation page.", "type": "string", "enum": [ "redirect", "hosted_confirmation" ], "example": "redirect" }, "HostedConfirmation": { "description": "Hosted confirmation page shown after a completed checkout when `after_completion.type` is `hosted_confirmation`.", "type": "object", "properties": { "custom_message": { "description": "A custom message displayed to the customer on the hosted confirmation page.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" } }, "example": { "custom_message": "Premium SPF 50 mineral sunscreen" } }, "Redirect": { "description": "Redirect behavior applied after a completed checkout when `after_completion.type` is `redirect`.", "type": "object", "required": [ "url" ], "properties": { "url": { "description": "The URL the customer is redirected to after completing the checkout.", "type": "string", "format": "uri", "example": "https://example.com" } }, "example": { "url": "https://example.com" } }, "PaymentLinkBody_for_CreatePaymentLink": { "description": "An envelope wrapping a single payment link object.", "type": "object", "required": [ "payment_link" ], "properties": { "payment_link": { "description": "The payment link.", "$ref": "#/components/schemas/CreatePaymentLink" } }, "example": { "payment_link": { "line_items": [ { "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } }, "quantity": 0, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "tax_rate": { "amount": 2500 }, "components": [ { "quantity": 1.0, "dressing_mode": "MIXED", "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string" } ] } ], "label": "Example", "shipping_address_collection": false, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "metadata": { "order_id": "8842", "channel": "shopify" }, "payment_intent_data": { "capture_method": "automatic", "metadata": { "order_id": "8842", "channel": "shopify" } }, "after_completion": { "type": "redirect", "hosted_confirmation": { "custom_message": "Premium SPF 50 mineral sunscreen" }, "redirect": { "url": "https://example.com" } }, "allow_promotion_codes": false, "origin": "shopify", "tax_rate": { "amount": 2500 }, "discounts": [ { "coupon_id": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "promo_code_id": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "coupon_data": { "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "name": "Coupon", "amount_off": 100, "duration": "once", "percent_off": 10.0, "max_redemptions": 100, "metadata": { "key": "value" } } } ], "mode": "payment", "setup_future_use": "on_session" } } }, "CreatePaymentLink": { "description": "Parameters for creating a payment link.", "type": "object", "properties": { "line_items": { "description": "The line items representing what is being sold. Required for payment/subscription modes. Must be empty or omitted for setup mode.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/NewLineItem" } }, "label": { "description": "Custom name shown for the payment link. When omitted, a label is auto-generated from the first line item's product (e.g. \"Product name and 2 more\"). Required for setup mode, where there are no products to derive a name from.", "type": [ "string", "null" ], "example": "Example" }, "shipping_address_collection": { "description": "Whether to collect a shipping address from the customer at checkout. Defaults to `false`.", "type": [ "boolean", "null" ], "example": false }, "shipping_options": { "description": "Shipping rate applied to checkout sessions generated from this link. Provide either an existing shipping rate ID or inline shipping rate data; inline data creates a new Shipping Rate. When omitted, no shipping fee is applied.", "anyOf": [ { "$ref": "#/components/schemas/ShippingRateOptionsRequest" }, { "type": "null" } ] }, "metadata": { "description": "Set of key-value pairs you can attach to the payment link for storing additional structured information.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "payment_intent_data": { "description": "Parameters passed through to the PaymentIntent created during checkout, such as the capture method and payment-intent-level metadata.", "anyOf": [ { "$ref": "#/components/schemas/PaymentIntentData" }, { "type": "null" } ] }, "after_completion": { "description": "Behavior after the customer completes a checkout session generated from this link. When omitted, defaults to showing the hosted confirmation page.", "anyOf": [ { "$ref": "#/components/schemas/AfterCompletion" }, { "type": "null" } ] }, "allow_promotion_codes": { "description": "Whether customers may enter promotion codes at checkout. Defaults to `false`.", "type": [ "boolean", "null" ], "example": false }, "origin": { "description": "The integration or surface this payment link originated from. `null` for links created directly via the API. Setting `renewal` is rejected: that origin is reserved for sessions Flex mints itself.", "anyOf": [ { "$ref": "#/components/schemas/CheckoutSessionOrigin" }, { "type": "null" } ] }, "tax_rate": { "description": "Session-level flat tax amount in cents (e.g., 500 = $5.00)", "anyOf": [ { "$ref": "#/components/schemas/TaxRate" }, { "type": "null" } ] }, "discounts": { "description": "Discounts to apply when generating checkout sessions. Supports existing coupon IDs or inline coupon creation via coupon_data.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DiscountType" } }, "mode": { "description": "The mode of the checkout session. Defaults to \"payment\". `reimbursement` is rejected with `mode_not_supported`. Use \"setup\" to save a payment method without charging.", "anyOf": [ { "$ref": "#/components/schemas/Mode" }, { "type": "null" } ] }, "setup_future_use": { "description": "Controls how the payment method is saved for future use on checkout sessions generated from this link. Use \"off_session\" to save the card for future merchant-initiated charges, or \"on_session\" for payments where the customer is present. When omitted, defaults based on mode (\"setup\" → \"off_session\", otherwise \"on_session\").", "anyOf": [ { "$ref": "#/components/schemas/FutureUse" }, { "type": "null" } ] } }, "example": { "line_items": [ { "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } }, "quantity": 0, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "tax_rate": { "amount": 2500 }, "components": [ { "quantity": 1.0, "dressing_mode": "MIXED", "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string" } ] } ], "label": "Example", "shipping_address_collection": false, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "metadata": { "order_id": "8842", "channel": "shopify" }, "payment_intent_data": { "capture_method": "automatic", "metadata": { "order_id": "8842", "channel": "shopify" } }, "after_completion": { "type": "redirect", "hosted_confirmation": { "custom_message": "Premium SPF 50 mineral sunscreen" }, "redirect": { "url": "https://example.com" } }, "allow_promotion_codes": false, "origin": "shopify", "tax_rate": { "amount": 2500 }, "discounts": [ { "coupon_id": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "promo_code_id": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "coupon_data": { "applies_to": { "products": [ "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ] }, "name": "Coupon", "amount_off": 100, "duration": "once", "percent_off": 10.0, "max_redemptions": 100, "metadata": { "key": "value" } } } ], "mode": "payment", "setup_future_use": "on_session" } }, "PaymentLinkBody_for_PaymentLink": { "description": "An envelope wrapping a single payment link object.", "type": "object", "required": [ "payment_link" ], "properties": { "payment_link": { "description": "The payment link.", "$ref": "#/components/schemas/PaymentLink" } }, "example": { "payment_link": { "payment_link_id": "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "label": "Example", "active": false, "line_items": [ { "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } }, "quantity": 0, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_rate_data": { "display_name": "Example", "amount": 2500, "metadata": { "order_id": "8842", "channel": "shopify" } } }, "tax_rate": { "amount": 2500 }, "components": [ { "quantity": 1.0, "dressing_mode": "MIXED", "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "string" } ] } ], "allow_promotion_codes": false, "shipping_address_collection": false, "shipping_options": { "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "shipping_amount": 2500, "display_name": "Example" }, "metadata": { "order_id": "8842", "channel": "shopify" }, "url": "https://example.com", "created_at": "2026-06-15T14:30:00Z", "payment_intent_data": { "capture_method": "automatic", "metadata": { "order_id": "8842", "channel": "shopify" } }, "after_completion": { "type": "redirect", "hosted_confirmation": { "custom_message": "Premium SPF 50 mineral sunscreen" }, "redirect": { "url": "https://example.com" } }, "origin": "shopify", "tax_rate": { "amount": 2500 }, "discounts": [ "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA" ], "setup_future_use": "on_session", "test_mode": false } } }, "PaymentLinkBody_for_UpdatePaymentLinkRequest": { "description": "An envelope wrapping a single payment link object.", "type": "object", "required": [ "payment_link" ], "properties": { "payment_link": { "description": "The payment link.", "$ref": "#/components/schemas/UpdatePaymentLinkRequest" } }, "example": { "payment_link": { "label": "Example", "after_completion": { "type": "redirect", "hosted_confirmation": { "custom_message": "Premium SPF 50 mineral sunscreen" }, "redirect": { "url": "https://example.com" } }, "active": false, "shipping_address_collection": false } } }, "UpdatePaymentLinkRequest": { "description": "Parameters for updating a payment link. Only the supplied fields are changed; omitted fields are left unchanged.", "type": "object", "properties": { "label": { "description": "Custom name shown for the payment link. Omit to leave the current label unchanged.", "type": [ "string", "null" ], "example": "Example" }, "after_completion": { "description": "Behavior after the customer completes a checkout session generated from this link. Omit to leave the current behavior unchanged.", "anyOf": [ { "$ref": "#/components/schemas/AfterCompletion" }, { "type": "null" } ] }, "active": { "description": "Set to false to archive this payment link. Inactive payment links are hidden from list views by default.", "type": [ "boolean", "null" ], "example": false }, "shipping_address_collection": { "description": "Whether to collect a shipping address from the customer at checkout. Omit to leave the current setting unchanged.", "type": [ "boolean", "null" ], "example": false } }, "example": { "label": "Example", "after_completion": { "type": "redirect", "hosted_confirmation": { "custom_message": "Premium SPF 50 mineral sunscreen" }, "redirect": { "url": "https://example.com" } }, "active": false, "shipping_address_collection": false } }, "MultiplePayoutsBody_for_Payout": { "description": "An envelope wrapping a list of payout objects.", "type": "object", "required": [ "payouts" ], "properties": { "payouts": { "description": "The list of payouts.", "type": "array", "items": { "$ref": "#/components/schemas/Payout" } } }, "example": { "payouts": [ { "payout_id": "fpo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "in_transit", "amount": 2500, "arrival_date": "string", "created_at": "2026-06-15T14:30:00Z", "source_type": "string", "test_mode": false, "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ] } }, "Payout": { "description": "A Payout represents a transfer of funds from your Flex balance to your bank account. It aggregates the balance transactions that settle in a given payout and tracks the payout's status and arrival date.", "type": "object", "required": [ "amount", "arrival_date", "created_at", "payout_id", "status", "test_mode" ], "properties": { "payout_id": { "description": "Unique identifier for the payout, prefixed with `fpo_`.", "type": "string", "example": "fpo_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "status": { "description": "Status of the payout: `in_transit` (on its way to the bank), `paid` (deposited), `failed` (could not be completed), or `canceled`.", "$ref": "#/components/schemas/Status3" }, "amount": { "description": "Amount paid out, in the smallest currency unit (e.g., `150000` = $1,500.00 USD).", "type": "integer", "format": "int32", "example": 2500, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "arrival_date": { "description": "When the payout is expected to arrive in your bank account. RFC 3339 timestamp.", "$ref": "#/components/schemas/Timestamptz" }, "created_at": { "description": "When the payout was created. RFC 3339 timestamp.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "source_type": { "description": "The kind of balance the payout was drawn from (e.g., `card`, `bank_account`).", "type": [ "string", "null" ] }, "test_mode": { "description": "Whether this payout was created in test mode. `true` for test-mode data, `false` for live data.", "type": "boolean", "example": false }, "balance_transaction": { "description": "Balance transaction that describes the impact of this payout on your balance. Defaults to the balance transaction ID; always serialized, `null` for payouts without a linked balance transaction yet.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_BalanceTransaction" }, { "type": "null" } ] }, "failure_balance_transaction": { "description": "Reversal balance transaction created when a payout fails and funds are credited back. Always serialized; `null` on the common success path.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_BalanceTransaction" }, { "type": "null" } ] } }, "example": { "payout_id": "fpo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "in_transit", "amount": 2500, "arrival_date": "string", "created_at": "2026-06-15T14:30:00Z", "source_type": "string", "test_mode": false, "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "Status3": { "type": "string", "enum": [ "in_transit", "paid", "failed", "canceled" ], "x-ms-enum": { "name": "Status3", "modelAsString": false, "values": [ { "value": "in_transit", "name": "InTransit", "description": "The payout has been initiated and is on its way to the bank account." }, { "value": "paid", "name": "Paid", "description": "The payout has been deposited into the bank account." }, { "value": "failed", "name": "Failed", "description": "The payout could not be completed." }, { "value": "canceled", "name": "Canceled", "description": "The payout was canceled before it completed." } ] }, "description": "Status of a payout.\n\n- `in_transit`: The payout has been initiated and is on its way to the bank account.\n- `paid`: The payout has been deposited into the bank account.\n- `failed`: The payout could not be completed.\n- `canceled`: The payout was canceled before it completed.", "example": "in_transit" }, "MultiplePriceBody_for_Price": { "description": "An envelope wrapping a list of price objects.", "type": "object", "required": [ "prices" ], "properties": { "prices": { "description": "The list of prices.", "type": "array", "items": { "$ref": "#/components/schemas/Price" } } }, "example": { "prices": [ { "price_id": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "trial_period_days": 0, "unit_amount": 0, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "active": false, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "type": "one_time", "metadata": { "order_id": "8842", "channel": "shopify" }, "lookup_key": "standard_monthly", "hsa_fsa_eligibility": "not_eligible", "test_mode": false } ] } }, "PriceBody_for_NewPriceRequest": { "description": "An envelope wrapping a single price object.", "type": "object", "required": [ "price" ], "properties": { "price": { "description": "The price object.", "$ref": "#/components/schemas/NewPriceRequest" } }, "example": { "price": { "lookup_key": "standard_monthly", "transfer_lookup_key": true, "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } } } }, "NewPriceRequest": { "description": "Parameters for creating a price. Reference an existing product with `product`, or create one inline with `product_data`.", "type": "object", "properties": { "lookup_key": { "description": "A stable, partner-owned key for this price, unique within your account and mode across all prices — archived ones included. Up to 200 characters.", "type": [ "string", "null" ], "maxLength": 200, "example": "standard_monthly" }, "transfer_lookup_key": { "description": "Move `lookup_key` off whichever price currently holds it — active or archived — and onto this one, in a single request. The other price stays usable; only its `lookup_key` is cleared. Without this, claiming a key another price holds is rejected.", "type": [ "boolean", "null" ] }, "description": { "description": "A brief description of the price.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" }, "unit_amount": { "description": "A positive integer in cents (or 0 for a free price) representing how much to charge.", "type": "integer", "format": "int64", "minimum": 0.0, "example": 2500, "maximum": 4294967295.0 }, "recurring": { "description": "The recurring components of a price such as interval and trial period days.", "anyOf": [ { "$ref": "#/components/schemas/Recurring" }, { "type": "null" } ] }, "metadata": { "description": "Metadata to attach to the price.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "product": { "description": "The ID of the product that this price will belong to.", "type": "string", "example": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "product_data": { "description": "Data used to generate a new Product object inline.", "$ref": "#/components/schemas/CreateProductRequest" } }, "required": [ "unit_amount" ], "example": { "lookup_key": "standard_monthly", "transfer_lookup_key": true, "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } } }, "PriceBody_for_Price": { "description": "An envelope wrapping a single price object.", "type": "object", "required": [ "price" ], "properties": { "price": { "description": "The price object.", "$ref": "#/components/schemas/Price" } }, "example": { "price": { "price_id": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "owner_partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "trial_period_days": 0, "unit_amount": 0, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "active": false, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "type": "one_time", "metadata": { "order_id": "8842", "channel": "shopify" }, "lookup_key": "standard_monthly", "hsa_fsa_eligibility": "not_eligible", "test_mode": false } } }, "PriceBody_for_UpdatePrice": { "description": "An envelope wrapping a single price object.", "type": "object", "required": [ "price" ], "properties": { "price": { "description": "The price object.", "$ref": "#/components/schemas/UpdatePrice" } }, "example": { "price": { "description": "Premium SPF 50 mineral sunscreen", "active": false, "lookup_key": "standard_monthly", "transfer_lookup_key": false } } }, "UpdatePrice": { "description": "Parameters for updating an existing price. Only the fields you supply are changed; omitted fields are left unchanged.", "type": "object", "properties": { "description": { "description": "An arbitrary string attached to the price, often shown to the customer. Omitted or `null` values leave the existing description unchanged.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" }, "active": { "description": "Whether the price can be used for new purchases. Set to `false` to archive the price; existing subscriptions on it are unaffected.", "type": [ "boolean", "null" ], "example": false }, "lookup_key": { "description": "A stable, partner-owned key for this price, unique within your account and mode across all prices — archived ones included. Up to 200 characters. Send `null` to release the key; omit the field to leave it as it is.", "default": null, "type": [ "string", "null" ], "maxLength": 200, "example": "standard_monthly" }, "transfer_lookup_key": { "description": "Take `lookup_key` from whichever price currently holds it instead of failing. The previous holder keeps its `active` state and simply loses the key.", "type": [ "boolean", "null" ], "example": false } }, "example": { "description": "Premium SPF 50 mineral sunscreen", "active": false, "lookup_key": "standard_monthly", "transfer_lookup_key": false } }, "MultiplePromoCodesBody_for_PromoCode": { "description": "An envelope wrapping a list of promotion code objects.", "type": "object", "required": [ "promo_codes" ], "properties": { "promo_codes": { "description": "The list of promotion codes.", "type": "array", "items": { "$ref": "#/components/schemas/PromoCode" } } }, "example": { "promo_codes": [ { "promo_code_id": "fpromo_01HACM7FZ1084XB1GB6053VM0E", "code": "SUMMER2016", "coupon": { "coupon_id": "fcoup_1234567890", "amount_off": 100, "applies_to": null, "duration": "once", "duration_in_months": null, "metadata": { "key": "value" }, "name": "Coupon", "percent_off": 10.0, "max_redemptions": 100, "times_redeemed": 0, "valid": true, "created_at": "2024-05-17T14:59:21Z", "test_mode": true }, "max_redemptions": 100, "times_redeemed": 0, "created_at": "2024-05-17T14:59:21Z", "customer": "fcus_01HACM7FZ1084XB1GB6053VM0D", "active": true, "metadata": { "key": "value" }, "test_mode": false } ] } }, "PromoCode": { "description": "A promo code represents a code for a coupon that can be redeemed by a customer.", "type": "object", "required": [ "active", "code", "coupon", "created_at", "promo_code_id", "test_mode", "times_redeemed" ], "properties": { "promo_code_id": { "description": "The ID of the promo code.", "type": "string", "example": "fpromo_01HACM7FZ1084XB1GB6053VM0E" }, "code": { "description": "The customer-facing code. Regardless of case, this code must be unique across all active", "type": "string", "example": "SUMMER2016" }, "coupon": { "description": "The coupon that the promo code represents.", "$ref": "#/components/schemas/V1Coupon", "example": { "coupon_id": "fcoup_1234567890", "amount_off": 100, "applies_to": null, "duration": "once", "duration_in_months": null, "metadata": { "key": "value" }, "name": "Coupon", "percent_off": 10.0, "max_redemptions": 100, "times_redeemed": 0, "valid": true, "created_at": "2024-05-17T14:59:21Z", "test_mode": true } }, "max_redemptions": { "description": "The number of times the promo code can be redeemed.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 100, "minimum": -2147483648.0 }, "times_redeemed": { "description": "The number of times the promo code has been redeemed.", "type": "integer", "format": "int32", "example": 0, "minimum": -2147483648.0, "maximum": 2147483647.0 }, "created_at": { "description": "The date and time the promo code was created.", "$ref": "#/components/schemas/Timestamptz", "example": "2024-05-17T14:59:21Z" }, "customer": { "description": "The customer that can be associated with the promo code. If null, the promo code can be redeemed by any customer.", "type": [ "string", "null" ], "example": "fcus_01HACM7FZ1084XB1GB6053VM0D" }, "active": { "description": "Whether the promo code is currently active.", "type": "boolean", "example": true }, "metadata": { "description": "Metadata associated with the promo code.", "type": [ "object", "null" ], "example": { "key": "value" } }, "test_mode": { "description": "Whether the promo code is in test mode.", "type": "boolean", "example": false } }, "example": { "promo_code_id": "fpromo_01HACM7FZ1084XB1GB6053VM0E", "code": "SUMMER2016", "coupon": { "coupon_id": "fcoup_1234567890", "amount_off": 100, "applies_to": null, "duration": "once", "duration_in_months": null, "metadata": { "key": "value" }, "name": "Coupon", "percent_off": 10.0, "max_redemptions": 100, "times_redeemed": 0, "valid": true, "created_at": "2024-05-17T14:59:21Z", "test_mode": true }, "max_redemptions": 100, "times_redeemed": 0, "created_at": "2024-05-17T14:59:21Z", "customer": "fcus_01HACM7FZ1084XB1GB6053VM0D", "active": true, "metadata": { "key": "value" }, "test_mode": false } }, "PromoCodeBody_for_CreatePromoCodeRequest": { "description": "An envelope wrapping a single promotion code object.", "type": "object", "required": [ "promo_code" ], "properties": { "promo_code": { "description": "The promotion code.", "$ref": "#/components/schemas/CreatePromoCodeRequest" } }, "example": { "promo_code": { "coupon_id": "fcoup_1234567890", "code": "SUMMER2016", "max_redemptions": 100, "customer": "fcus_01HACM7FZ1084XB1GB6053VM0D", "metadata": { "key": "value" } } } }, "CreatePromoCodeRequest": { "description": "Parameters for creating a promotion code that customers redeem to apply an existing coupon.", "type": "object", "required": [ "coupon_id" ], "properties": { "coupon_id": { "description": "ID of the Coupon this promotion code applies.", "type": "string", "example": "fcoup_1234567890" }, "code": { "description": "The customer-facing code. Must be unique across your promotion codes. If null, a code is generated automatically.", "type": [ "string", "null" ], "example": "SUMMER2016" }, "max_redemptions": { "description": "The number of times the promo code can be redeemed.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 100, "minimum": -2147483648.0 }, "customer": { "description": "The customer that can be associated with the promo code. If null, the promo code can be redeemed by any customer.", "type": [ "string", "null" ], "example": "fcus_01HACM7FZ1084XB1GB6053VM0D" }, "metadata": { "description": "Metadata associated with the promo code.", "type": [ "object", "null" ], "example": { "key": "value" } } }, "example": { "coupon_id": "fcoup_1234567890", "code": "SUMMER2016", "max_redemptions": 100, "customer": "fcus_01HACM7FZ1084XB1GB6053VM0D", "metadata": { "key": "value" } } }, "PromoCodeBody_for_PromoCode": { "description": "An envelope wrapping a single promotion code object.", "type": "object", "required": [ "promo_code" ], "properties": { "promo_code": { "description": "The promotion code.", "$ref": "#/components/schemas/PromoCode" } }, "example": { "promo_code": { "promo_code_id": "fpromo_01HACM7FZ1084XB1GB6053VM0E", "code": "SUMMER2016", "coupon": { "coupon_id": "fcoup_1234567890", "amount_off": 100, "applies_to": null, "duration": "once", "duration_in_months": null, "metadata": { "key": "value" }, "name": "Coupon", "percent_off": 10.0, "max_redemptions": 100, "times_redeemed": 0, "valid": true, "created_at": "2024-05-17T14:59:21Z", "test_mode": true }, "max_redemptions": 100, "times_redeemed": 0, "created_at": "2024-05-17T14:59:21Z", "customer": "fcus_01HACM7FZ1084XB1GB6053VM0D", "active": true, "metadata": { "key": "value" }, "test_mode": false } } }, "PromoCodeBody_for_UpdatePromoCodeRequest": { "description": "An envelope wrapping a single promotion code object.", "type": "object", "required": [ "promo_code" ], "properties": { "promo_code": { "description": "The promotion code.", "$ref": "#/components/schemas/UpdatePromoCodeRequest" } }, "example": { "promo_code": { "active": false, "metadata": { "key": "value" } } } }, "UpdatePromoCodeRequest": { "description": "Parameters for updating a promotion code. Only `active` and `metadata` can be changed; the referenced coupon and the code itself are immutable.", "type": "object", "properties": { "active": { "description": "Specifies whether the promo code is currently active.", "type": [ "boolean", "null" ], "example": false }, "metadata": { "description": "Metadata associated with the promo code.", "type": [ "object", "null" ], "example": { "key": "value" } } }, "example": { "active": false, "metadata": { "key": "value" } } }, "MultipleRefundsBody_for_Refund": { "description": "An envelope wrapping a list of refund objects.", "type": "object", "required": [ "refunds" ], "properties": { "refunds": { "description": "The list of refund objects.", "type": "array", "items": { "$ref": "#/components/schemas/Refund" } } }, "example": { "refunds": [ { "refund_id": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "created_at": "2026-06-15T14:30:00Z", "reason": "duplicate", "status": "pending", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available", "items": [ { "amount_refunded": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available" } ], "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ] } }, "RefundBody_for_CreateRefund": { "description": "An envelope wrapping a single refund object.", "type": "object", "required": [ "refund" ], "properties": { "refund": { "description": "The refund object.", "$ref": "#/components/schemas/CreateRefund" } }, "example": { "refund": { "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "reason": "duplicate", "metadata": { "order_id": "8842", "channel": "shopify" } } } }, "CreateRefund": { "description": "Parameters for creating a refund against a succeeded payment intent.", "type": "object", "required": [ "payment_intent_id" ], "properties": { "payment_intent_id": { "description": "ID of the PaymentIntent to refund. The payment intent must have a `succeeded` status.", "type": "string", "example": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "amount": { "description": "Amount to refund, in the smallest currency unit (e.g., `2500` = $25.00 USD). When omitted, the full amount of the payment intent is refunded.", "type": [ "integer", "null" ], "format": "int32", "maximum": 2147483647.0, "example": 2500, "minimum": -2147483648.0 }, "reason": { "description": "The reason for the refund. Optional.", "anyOf": [ { "$ref": "#/components/schemas/RefundReason" }, { "type": "null" } ] }, "metadata": { "description": "Set of key-value pairs you can attach to the refund for storing additional structured information.", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": { "order_id": "8842", "channel": "shopify" } } }, "example": { "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "reason": "duplicate", "metadata": { "order_id": "8842", "channel": "shopify" } } }, "RefundBody_for_Refund": { "description": "An envelope wrapping a single refund object.", "type": "object", "required": [ "refund" ], "properties": { "refund": { "description": "The refund object.", "$ref": "#/components/schemas/Refund" } }, "example": { "refund": { "refund_id": "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "created_at": "2026-06-15T14:30:00Z", "reason": "duplicate", "status": "pending", "test_mode": false, "metadata": { "order_id": "8842", "channel": "shopify" }, "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available", "items": [ { "amount_refunded": 2500, "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reference_type": "acquirer_reference_number", "reference_status": "available" } ], "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice_id": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "failure_balance_transaction": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } }, "RefundBody_for_UpdateRefundRequest": { "description": "An envelope wrapping a single refund object.", "type": "object", "required": [ "refund" ], "properties": { "refund": { "description": "The refund object.", "$ref": "#/components/schemas/UpdateRefundRequest" } }, "example": { "refund": { "reason": "duplicate", "metadata": { "order_id": "8842", "channel": "shopify" } } } }, "UpdateRefundRequest": { "description": "Parameters for updating a refund. Only `reason` and `metadata` can be changed; all fields are optional and omitted fields are left unchanged.", "type": "object", "properties": { "reason": { "description": "The reason for the refund.", "anyOf": [ { "$ref": "#/components/schemas/RefundReason" }, { "type": "null" } ] }, "metadata": { "description": "Set of key-value pairs to attach to the refund. Supplied keys are merged into any existing metadata rather than replacing it.", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": { "order_id": "8842", "channel": "shopify" } } }, "example": { "reason": "duplicate", "metadata": { "order_id": "8842", "channel": "shopify" } } }, "MultipleReviewsBody_for_Review": { "description": "An envelope wrapping a list of review objects.", "type": "object", "required": [ "reviews" ], "properties": { "reviews": { "description": "The list of reviews.", "type": "array", "items": { "$ref": "#/components/schemas/Review" } } }, "example": { "reviews": [ { "review_id": "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reason": "rule", "opened_reason": "rule", "closed_reason": "approved", "open": false, "billing_zip": "string", "ip_address": "string", "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z" } ] } }, "ReviewBody_for_Review": { "description": "An envelope wrapping a single review object.", "type": "object", "required": [ "review" ], "properties": { "review": { "description": "The review object.", "$ref": "#/components/schemas/Review" } }, "example": { "review": { "review_id": "frv_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "reason": "rule", "opened_reason": "rule", "closed_reason": "approved", "open": false, "billing_zip": "string", "ip_address": "string", "test_mode": false, "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z" } } }, "MultipleSubscriptionBody_for_Array_of_Subscription": { "description": "An envelope wrapping a list of subscription objects.", "type": "object", "required": [ "subscriptions" ], "properties": { "subscriptions": { "description": "The list of subscriptions.", "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } } }, "example": { "subscriptions": [ { "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "quantity": 2500, "created_at": "2026-06-15T14:30:00Z", "updated_at": "2026-06-15T14:30:00Z", "test_mode": false } ], "latest_invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "incomplete", "cancel_at_period_end": false, "current_period_end": "string", "current_period_start": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false, "client_secret": { "setup_secret": "string", "payment_secret": "string" }, "proration_behavior": "always_invoice", "trial_start": "string", "trial_end": "string", "cancel_at": "2026-06-15T14:30:00Z", "canceled_at": "2026-06-15T14:30:00Z", "default_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "discounts": [ { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } ], "pause": { "paused_at": "2026-06-15T14:30:00Z", "resume_at": "2026-06-15T14:30:00Z" } } ] } }, "SubscriptionBody_for_Subscription": { "description": "An envelope wrapping a single subscription object.", "type": "object", "required": [ "subscription" ], "properties": { "subscription": { "description": "The subscription payload carried by the request or response.", "$ref": "#/components/schemas/Subscription" } }, "example": { "subscription": { "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "quantity": 2500, "created_at": "2026-06-15T14:30:00Z", "updated_at": "2026-06-15T14:30:00Z", "test_mode": false } ], "latest_invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "incomplete", "cancel_at_period_end": false, "current_period_end": "string", "current_period_start": "string", "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false, "client_secret": { "setup_secret": "string", "payment_secret": "string" }, "proration_behavior": "always_invoice", "trial_start": "string", "trial_end": "string", "cancel_at": "2026-06-15T14:30:00Z", "canceled_at": "2026-06-15T14:30:00Z", "default_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "discounts": [ { "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "source": { "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "coupon" }, "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "end": "string", "start": "string" } ], "pause": { "paused_at": "2026-06-15T14:30:00Z", "resume_at": "2026-06-15T14:30:00Z" } } } }, "SubscriptionBody_for_CancelSubscriptionRequest": { "description": "An envelope wrapping a single subscription object.", "type": "object", "required": [ "subscription" ], "properties": { "subscription": { "description": "The subscription payload carried by the request or response.", "$ref": "#/components/schemas/CancelSubscriptionRequest" } }, "example": { "subscription": { "cancel_at_period_end": false, "refund": "none", "refund_amount": 2500 } } }, "CancelSubscriptionRequest": { "description": "Options for canceling a subscription: whether to cancel immediately or at period end, and whether to issue a refund as part of the cancellation.", "type": "object", "properties": { "cancel_at_period_end": { "description": "If true, cancel at end of current billing period. If false or omitted, cancel immediately. `true` is refused while the subscription is paused.", "type": [ "boolean", "null" ], "example": false }, "refund": { "description": "Type of refund to issue with the cancellation. \"full\": refund full amount of latest invoice \"prorated\": refund prorated amount based on remaining billing period \"custom\": refund a specific amount (requires `refund_amount`) \"none\" (default): cancel only, no refund. For a paused subscription, the refund comes from the invoice paid before the pause, and \"prorated\" refunds the time left at the pause.", "anyOf": [ { "$ref": "#/components/schemas/RefundType" }, { "type": "null" } ] }, "refund_amount": { "description": "Custom refund amount in cents. Required when `refund` is \"custom\".", "type": [ "integer", "null" ], "format": "int64", "maximum": 9007199254740991.0, "example": 2500, "minimum": -9007199254740991.0 } }, "example": { "cancel_at_period_end": false, "refund": "none", "refund_amount": 2500 } }, "RefundType": { "type": "string", "enum": [ "none", "full", "prorated", "custom" ], "x-ms-enum": { "name": "RefundType", "modelAsString": false, "values": [ { "value": "none", "name": "None", "description": "Cancel only, no refund (default behavior)" }, { "value": "full", "name": "Full", "description": "Full refund of the latest invoice amount" }, { "value": "prorated", "name": "Prorated", "description": "Prorated refund based on remaining time in billing period" }, { "value": "custom", "name": "Custom", "description": "Custom refund amount specified by `refund_amount` (in cents)" } ] }, "description": "Type of refund to issue with a subscription cancellation.\n\n- `none`: Cancel only, no refund (default behavior)\n- `full`: Full refund of the latest invoice amount\n- `prorated`: Prorated refund based on remaining time in billing period\n- `custom`: Custom refund amount specified by `refund_amount` (in cents)", "example": "none" }, "SubscriptionBody_for_UpdateSubscriptionRequest": { "description": "An envelope wrapping a single subscription object.", "type": "object", "required": [ "subscription" ], "properties": { "subscription": { "description": "The subscription payload carried by the request or response.", "$ref": "#/components/schemas/UpdateSubscriptionRequest" } }, "example": { "subscription": { "cancel_at_period_end": false, "trial_end": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } } } ], "proration_behavior": "always_invoice", "cancel_at": "2026-06-15T14:30:00Z", "metadata": { "order_id": "8842", "channel": "shopify" }, "coupon": "string", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } }, "UpdateSubscriptionRequest": { "description": "Parameters for updating a subscription. Any omitted field is left unchanged.", "type": "object", "properties": { "cancel_at_period_end": { "description": "Whether this subscription should cancel at the end of the current period (current_period_end). Refused while the subscription is paused.", "type": [ "boolean", "null" ], "example": false }, "trial_end": { "description": "When this subscription ends This is in ISO 8601 format, example: 2026-02-07T18:26:40+00:00", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" }, "items": { "description": "items to update", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/UpdateSubscriptionItemRequest" } }, "proration_behavior": { "description": "Proration behavior. Determines how to handle prorations when the billing cycle changes (e.g., when switching plans or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. Refused while the subscription is paused.", "anyOf": [ { "$ref": "#/components/schemas/FlexSubscriptionProrationBehavior" }, { "type": "null" } ] }, "cancel_at": { "description": "A date in the future at which the subscription will automatically get canceled. This is in ISO 8601 format, example: 2026-02-07T18:26:40+00:00. Refused while the subscription is paused.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" }, "metadata": { "description": "A set of key/value pairs that you can attach to a subscription object.", "type": [ "object", "null" ], "example": { "order_id": "8842", "channel": "shopify" } }, "coupon": { "description": "The ID of the coupon to apply to this subscription. Pass an empty string `\"\"` to remove an existing coupon.", "type": [ "string", "null" ] }, "backup_payment_method": { "description": "The payment method charged when the default one fails.\n\nOmit the field to leave the current backup alone, pass `null` to clear it, or pass a payment method ID (`fpm_…`) to set it. The card must belong to the subscription's customer, be saved for off-session use, be a credit or debit card, and differ from the card the subscription bills.", "type": [ "string", "null" ], "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "example": { "cancel_at_period_end": false, "trial_end": "2026-06-15T14:30:00Z", "items": [ { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } } } ], "proration_behavior": "always_invoice", "cancel_at": "2026-06-15T14:30:00Z", "metadata": { "order_id": "8842", "channel": "shopify" }, "coupon": "string", "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "UpdateSubscriptionItemRequest": { "description": "Describes how to update a single item on a subscription: which item to change and the price to switch it to.", "type": "object", "properties": { "subscription_item_id": { "description": "The subscription item ID to update.", "type": "string", "example": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "price": { "description": "ID of an existing recurring Price to switch the item to. The price must be recurring; a one-time price is rejected with a 422.", "type": "string", "example": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "price_data": { "description": "Inline definition of a new recurring Price to create and assign to the item. Must reference an active product and include a `recurring` interval.", "$ref": "#/components/schemas/InlinePriceDataRequest" } }, "required": [ "subscription_item_id" ], "example": { "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "price_data": { "description": "Premium SPF 50 mineral sunscreen", "unit_amount": 2500, "recurring": { "interval": "day", "interval_count": 0, "trial_period_days": 0 }, "metadata": { "order_id": "8842", "channel": "shopify" }, "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "product_data": { "name": "Example", "description": "Premium SPF 50 mineral sunscreen", "upc_code": "example_value", "gtin": "example_value", "reference_gtin": "example_value", "url": "https://example.com", "client_reference_id": "example_value", "metadata": { "order_id": "8842", "channel": "shopify" }, "image_urls": [ "https://example.com/image.png" ], "categories": [ "string" ], "components": [ "string" ] } } } }, "ResendReceiptsResponse2": { "description": "Response returned after queuing receipt emails for resending.", "type": "object", "required": [ "receipt_ids" ], "properties": { "receipt_ids": { "description": "The receipt IDs that were queued for resending.", "type": "array", "items": { "type": "string" } } }, "example": { "receipt_ids": [ "string" ] } }, "RefundPreviewResponse": { "description": "The result of previewing a prorated refund for a subscription cancellation, without issuing any refund. Reflects what would be refunded based on the remaining billing period.", "type": "object", "required": [ "current_period_end", "current_period_start", "invoice_amount_paid", "prorated_amount_available_to_refund" ], "properties": { "prorated_amount_available_to_refund": { "description": "Prorated amount available to refund, in the smallest currency unit (e.g., `1499` = $14.99 USD), based on the unused portion of the current billing period.", "type": "integer", "format": "int64", "example": 2500, "minimum": -9007199254740991.0, "maximum": 9007199254740991.0 }, "invoice_amount_paid": { "description": "Total amount paid on the subscription's latest invoice, in the smallest currency unit (e.g., `2999` = $29.99 USD). For a paused subscription, the invoice paid before the pause.", "type": "integer", "format": "int64", "example": 2500, "minimum": -9007199254740991.0, "maximum": 9007199254740991.0 }, "current_period_start": { "description": "Start of the current billing period, as an RFC 3339 timestamp.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "current_period_end": { "description": "End of the current billing period, as an RFC 3339 timestamp. For a paused subscription, the period end before the pause, which the proration runs to.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "payment_method_id": { "description": "The payment method ID that would be refunded, if available", "type": [ "string", "null" ], "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "last4": { "description": "Last 4 digits of the card that would be refunded, if available", "type": [ "string", "null" ], "example": "4242" } }, "example": { "prorated_amount_available_to_refund": 2500, "invoice_amount_paid": 2500, "current_period_start": "2026-06-15T14:30:00Z", "current_period_end": "2026-06-15T14:30:00Z", "payment_method_id": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "last4": "4242" } }, "PauseSubscriptionRequest": { "description": "Options for pausing a subscription.", "type": "object", "properties": { "resume_at": { "description": "When Flex should resume the subscription. Must be in the future. Omit to keep the subscription paused until you resume it.", "default": null, "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" } }, "example": { "resume_at": "2026-06-15T14:30:00Z" } }, "ResumeSubscriptionRequest": { "description": "Options for resuming a paused subscription.", "type": "object", "properties": { "billing_cycle_anchor": { "description": "Where billing restarts. Defaults to `now`.", "default": null, "anyOf": [ { "$ref": "#/components/schemas/SubscriptionResumeBillingCycleAnchor" }, { "type": "null" } ], "example": "unchanged" }, "proration_behavior": { "description": "How the partial period is billed. Only with `billing_cycle_anchor: \"unchanged\"`, where it defaults to `create_prorations`.", "default": null, "anyOf": [ { "$ref": "#/components/schemas/SubscriptionResumeProrationBehavior" }, { "type": "null" } ], "example": "always_invoice" } }, "example": { "billing_cycle_anchor": "unchanged", "proration_behavior": "always_invoice" } }, "SubscriptionResumeBillingCycleAnchor": { "type": "string", "enum": [ "now", "unchanged" ], "x-ms-enum": { "name": "SubscriptionResumeBillingCycleAnchor", "modelAsString": false, "values": [ { "value": "now", "name": "Now", "description": "Bill the full period now, net of the unused time credited at the pause, and bill monthly from the resume date." }, { "value": "unchanged", "name": "Unchanged", "description": "Keep the original billing date." } ] }, "description": "Where billing restarts when a paused subscription resumes.\n\n- `now`: Bill the full period now, net of the unused time credited at the pause, and bill monthly from the resume date.\n- `unchanged`: Keep the original billing date.", "example": "now" }, "SubscriptionResumeProrationBehavior": { "type": "string", "enum": [ "create_prorations", "always_invoice" ], "x-ms-enum": { "name": "SubscriptionResumeProrationBehavior", "modelAsString": false, "values": [ { "value": "create_prorations", "name": "CreateProrations", "description": "Bill the partial period on the original billing date, with the next full period." }, { "value": "always_invoice", "name": "AlwaysInvoice", "description": "Bill the partial period now, net of the unused time credited at the pause. A negative amount charges nothing and goes to the customer's balance." } ] }, "description": "How the partial period is billed when a subscription resumes on its original billing date.\n\n- `create_prorations`: Bill the partial period on the original billing date, with the next full period.\n- `always_invoice`: Bill the partial period now, net of the unused time credited at the pause. A negative amount charges nothing and goes to the customer's balance.", "example": "create_prorations" }, "MultipleBalanceTransactionsBody_for_BalanceTransaction": { "description": "An envelope wrapping a list of balance transaction objects.", "type": "object", "required": [ "balance_transactions" ], "properties": { "balance_transactions": { "description": "The list of balance transactions.", "type": "array", "items": { "$ref": "#/components/schemas/BalanceTransaction" } } }, "example": { "balance_transactions": [ { "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "amount": 2500, "available_on": "string", "created_at": "2026-06-15T14:30:00Z", "exchange_rate": 1.0, "fee": 2500, "net": 2500, "reporting_category": "example_value", "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "status": "available", "source_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "type": "string", "flex_payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false, "mid": "example_value", "currency": "usd", "metadata": { "order_id": "8842", "channel": "shopify" }, "transaction_fee_amount": 0, "interchange_fee_amount": 0, "lmn_fee_amount": 0, "dispute_fee_amount": 0, "card_type": "string", "card_network": "string" } ] } }, "MultipleSetupIntentsBody_for_SetupIntent": { "description": "An envelope wrapping a list of setup intent objects.", "type": "object", "required": [ "setup_intents" ], "properties": { "setup_intents": { "description": "A list of SetupIntents.", "type": "array", "items": { "$ref": "#/components/schemas/SetupIntent" } } }, "example": { "setup_intents": [ { "setup_intent_id": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_secret": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "status": "requires_payment_method", "usage": "off_session", "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } ] } }, "SetupIntentBody_for_CreateSetupIntent": { "description": "An envelope wrapping a single setup intent object.", "type": "object", "required": [ "setup_intent" ], "properties": { "setup_intent": { "description": "The SetupIntent.", "$ref": "#/components/schemas/CreateSetupIntent" } }, "example": { "setup_intent": { "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } }, "CreateSetupIntent": { "description": "Parameters for creating a SetupIntent to collect a customer's payment method details.", "type": "object", "required": [ "checkout_session", "partner_id" ], "properties": { "partner_id": { "description": "ID of the account the SetupIntent is created for.", "type": "string", "example": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "checkout_session": { "description": "ID of the CheckoutSession the SetupIntent is associated with.", "type": "string", "example": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "example": { "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "SetupIntentBody_for_SetupIntent": { "description": "An envelope wrapping a single setup intent object.", "type": "object", "required": [ "setup_intent" ], "properties": { "setup_intent": { "description": "The SetupIntent.", "$ref": "#/components/schemas/SetupIntent" } }, "example": { "setup_intent": { "setup_intent_id": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_secret": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "status": "requires_payment_method", "usage": "off_session", "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } } }, "SetupIntentResponse": { "description": "SetupIntent response with expandable subscription", "type": "object", "required": [ "created_at", "partner_id", "setup_intent_id", "status", "test_mode", "usage" ], "properties": { "subscription": { "description": "The subscription this SetupIntent is associated with (expandable).", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_Subscription" }, { "type": "null" } ] }, "setup_intent_id": { "description": "The unique identifier for the object.", "type": "string", "example": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "client_secret": { "description": "The client secret used to confirm this SetupIntent from your frontend. Present when the SetupIntent is retrieved or created; `null` when it appears in a list response. Treat it as sensitive: do not log or store it, and expose it only to the customer over TLS.", "type": [ "string", "null" ] }, "customer": { "description": "The Customer this SetupIntent belongs to; returned as the ID by default and expandable to the full object.", "anyOf": [ { "$ref": "#/components/schemas/Expandable_for_Customer" }, { "type": "null" } ] }, "description": { "description": "An arbitrary string attached to the setup intent.", "type": [ "string", "null" ], "example": "Premium SPF 50 mineral sunscreen" }, "payment_method": { "description": "Payment method used with this SetupIntent.", "type": [ "string", "null" ], "example": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "partner_id": { "description": "The ID of the account this SetupIntent belongs to.", "type": "string", "example": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "metadata": { "description": "Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.", "type": [ "object", "null" ], "additionalProperties": { "type": "object" }, "example": { "order_id": "8842", "channel": "shopify" } }, "created_at": { "description": "Time at which the object was created. ISO 8601 format.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "test_mode": { "description": "Whether or not the setup intent is in test mode.", "type": "boolean", "example": false }, "status": { "description": "The current status of the setup intent.", "$ref": "#/components/schemas/Status2" }, "usage": { "description": "Indicates how the payment method is intended to be used in the future.", "$ref": "#/components/schemas/Usage" }, "subscription_id": { "description": "The ID of the Subscription this SetupIntent is associated with (for payment method updates).", "type": [ "string", "null" ], "example": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "example": { "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "setup_intent_id": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "client_secret": "string", "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "description": "Premium SPF 50 mineral sunscreen", "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "partner_id": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "metadata": { "order_id": "8842", "channel": "shopify" }, "created_at": "2026-06-15T14:30:00Z", "test_mode": false, "status": "requires_payment_method", "usage": "off_session", "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA" } }, "MultipleCapturesBody_for_V1Capture": { "description": "An envelope wrapping a list of capture objects.", "type": "object", "required": [ "captures" ], "properties": { "captures": { "description": "The list of captures.", "type": "array", "items": { "$ref": "#/components/schemas/V1Capture" } } }, "example": { "captures": [ { "amount_captured": 2500, "amount_shipping_captured": 2500, "amount_discount_captured": 2500, "amount_tax_captured": 2500, "capture_id": "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "amount_captured": 2500, "capture_item_id": "fcapi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false } ], "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false } ] } }, "CaptureBody_for_V1Capture": { "description": "An envelope wrapping a single capture object.", "type": "object", "required": [ "capture" ], "properties": { "capture": { "description": "The capture object.", "$ref": "#/components/schemas/V1Capture" } }, "example": { "capture": { "amount_captured": 2500, "amount_shipping_captured": 2500, "amount_discount_captured": 2500, "amount_tax_captured": 2500, "capture_id": "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "items": [ { "amount_captured": 2500, "capture_item_id": "fcapi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "created_at": "2026-06-15T14:30:00Z", "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "test_mode": false } ], "metadata": { "order_id": "8842", "channel": "shopify" }, "test_mode": false } } }, "CaptureBody_for_UpdateCaptureRequest": { "description": "An envelope wrapping a single capture object.", "type": "object", "required": [ "capture" ], "properties": { "capture": { "description": "The capture object.", "$ref": "#/components/schemas/UpdateCaptureRequest" } }, "example": { "capture": { "metadata": { "order_id": "8842", "channel": "shopify" } } } }, "UpdateCaptureRequest": { "description": "Parameters for updating an existing capture. Only the fields you provide are changed; omitted fields are left unmodified.", "type": "object", "properties": { "metadata": { "description": "Set of key-value pairs you can attach to the capture for storing additional structured information. Replaces the existing metadata when provided.", "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "example": { "order_id": "8842", "channel": "shopify" } } }, "example": { "metadata": { "order_id": "8842", "channel": "shopify" } } }, "FilePurpose": { "description": "What the uploaded file will be used for.", "type": "string", "enum": [ "account_requirement", "additional_verification", "business_icon", "business_logo", "customer_signature", "dispute_evidence", "document_provider_identity_document", "finance_report_run", "financial_account_statement", "identity_document", "identity_document_downloadable", "issuing_regulatory_reporting", "pci_document", "platform_terms_of_service", "selfie", "sigma_scheduled_query", "tax_document_user_upload", "terminal_android_apk", "terminal_reader_splashscreen" ], "example": "account_requirement" }, "MultipleFilesBody": { "description": "An envelope wrapping a list of file objects.", "type": "object", "required": [ "files" ], "properties": { "files": { "description": "The list of File objects.", "type": "array", "items": { "$ref": "#/components/schemas/V1File" } } }, "example": { "files": [ { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "purpose": "account_requirement", "filename": "string", "size": 0, "type": "string", "created_at": "2026-06-15T14:30:00Z", "expires_at": "2026-06-15T14:30:00Z" } ] } }, "V1File": { "description": "A File represents a document you uploaded to Flex, such as evidence to contest a dispute. Files are uploaded via the file upload endpoint and referenced by ID on other API objects.", "type": "object", "required": [ "created_at", "file_id", "purpose", "size" ], "properties": { "file_id": { "description": "Unique identifier for the file.", "type": "string", "example": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA" }, "purpose": { "description": "The purpose for which the file was uploaded, for example `dispute_evidence`. Determines how the file may be used elsewhere in the API.", "$ref": "#/components/schemas/FilePurpose" }, "filename": { "description": "The name of the uploaded file as it was supplied at upload time.", "type": [ "string", "null" ] }, "size": { "description": "Size of the file, in bytes.", "type": "integer", "format": "int64", "minimum": -9007199254740991.0, "maximum": 9007199254740991.0 }, "type": { "description": "The file's format, given as its extension, for example `pdf`, `png`, or `jpg`.", "type": [ "string", "null" ] }, "created_at": { "description": "Time at which the file was created, as an RFC 3339 timestamp.", "$ref": "#/components/schemas/Timestamptz", "example": "2026-06-15T14:30:00Z" }, "expires_at": { "description": "Time at which the file will expire and no longer be retrievable, as an RFC 3339 timestamp. `null` for files that do not expire.", "anyOf": [ { "$ref": "#/components/schemas/Timestamptz" }, { "type": "null" } ], "example": "2026-06-15T14:30:00Z" } }, "example": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "purpose": "account_requirement", "filename": "string", "size": 0, "type": "string", "created_at": "2026-06-15T14:30:00Z", "expires_at": "2026-06-15T14:30:00Z" } }, "CreateFileRequest": { "description": "Upload a file for use with the Flex API (e.g. dispute evidence).", "type": "object", "required": [ "file", "purpose" ], "properties": { "purpose": { "description": "The purpose of the file (e.g. \"dispute_evidence\").", "$ref": "#/components/schemas/FilePurpose" }, "file": { "description": "The file to upload (JPEG, PNG, or PDF, max 5MB).", "type": "string", "format": "binary" } }, "example": { "purpose": "account_requirement", "file": "string" } }, "FileBody": { "description": "An envelope wrapping a single file object.", "type": "object", "required": [ "file" ], "properties": { "file": { "description": "The File object.", "$ref": "#/components/schemas/V1File" } }, "example": { "file": { "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA", "purpose": "account_requirement", "filename": "string", "size": 0, "type": "string", "created_at": "2026-06-15T14:30:00Z", "expires_at": "2026-06-15T14:30:00Z" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Balance Transactions" }, { "name": "Captures" }, { "name": "Checkout Sessions" }, { "name": "Coupons" }, { "name": "Customers" }, { "name": "Disputes" }, { "name": "Events" }, { "name": "Exports" }, { "name": "Files" }, { "name": "Invoices" }, { "name": "Letters" }, { "name": "Orders" }, { "name": "Payment Intents" }, { "name": "Payment Links" }, { "name": "Payouts" }, { "name": "Prices" }, { "name": "Products" }, { "name": "Promo Codes" }, { "name": "Receipts" }, { "name": "Refunds" }, { "name": "Setup Intents" }, { "name": "Shipping Rates" }, { "name": "Subscriptions" } ], "x-speakeasy-retries": { "strategy": "backoff", "backoff": { "initialInterval": 500, "maxInterval": 60000, "maxElapsedTime": 3600000, "exponent": 1.5 }, "statusCodes": [ "5XX" ], "retryConnectionErrors": true } }