Checkout invitations
Email a checkout invitation
Invite the verified user who authorized the connection to review and submit a filer’s order.
/api/v1/orders/checkout/request- Authentication
- OAuth 2.0 access token
- Required scopes
orders.previewfilers.read- Idempotency key
- Required
- Rate-limit cost
- 5 units
How to use this endpoint
Provide filer and year, not a recipient selection. The user chooses services, payment and terms in checkout; opening the email does not charge or submit. Requests deduplicate by connection, user, filer, year, workflow and day. Checkout emails expire 24 hours after the original request. action=remind resends after at least five minutes, up to three sends per link, and invalidates older links without extending the original expiration. The response contains delivery metadata only. Reuse the same key after an uncertain result.
Choose workflow=efile for final filing services or workflow=tin_matching for a separate optional Bulk TIN Matching order. Different workflows have independent email identities; requesting matching does not replace a filing link. The human confirms services and follows ordinary order checkout. Read filing readiness first and offer matching only when tin_matching.advice=offer_matching.
The efile service is displayed as Combined Federal/State e-File (CF/SF). E-File Magic participates in the IRS CF/SF program for eligible filings. The API service_code remains efile; this display name does not change pricing or filing eligibility.
Retrying a request? Keep the same idempotency key and body after an uncertain result. A different key can repeat the action.
curl --request POST 'https://api.efilemagic.com/api/v1/orders/checkout/request' \
--header 'Authorization: Bearer <access-token>' \
--header 'Idempotency-Key: <unique-operation-key>' \
--header 'Content-Type: application/json' \
--data-binary @request.jsonReplace placeholders with your own values. Use the API resource origin provided for your environment.
Create request.json using the documented fields. Field descriptions are not sample values.
Request fields
4 fieldsfiler_idRequiredstring (uuid)
ID of the filer that owns this operation's records.
tax_yearRequiredinteger
Tax year of the filer and forms being processed. Allowed values: 2022, 2023, 2024, 2025, 2026.
actionOptionalstring
Request the initial checkout email or explicitly remind the authorizing user. Allowed values: "request", "remind". Default: "request".
workflowOptionalstring
Separate human checkout intent. Filing checkout never offers TIN Matching as an add-on. Use tin_matching for a distinct optional order before filing. Allowed values: "efile", "tin_matching". Default: "efile".
Headers (2)
AuthorizationRequired- OAuth Bearer token with the listed scopes and current resource authorization.
Idempotency-KeyRequired- Reuse the same key and request after an uncertain response.
curl --request POST 'https://api.efilemagic.com/api/v1/orders/checkout/request' \
--header 'Authorization: Bearer <access-token>' \
--header 'Idempotency-Key: <unique-operation-key>' \
--header 'Content-Type: application/json' \
--data-binary @request.jsonReplace placeholders with your own values. Use the API resource origin provided for your environment.
Create request.json using the documented fields. Field descriptions are not sample values.
Retrying a request? Keep the same idempotency key and body after an uncertain result. A different key can repeat the action.
On success, data contains the fields below. meta includes api_version and request_id. Keep request_id when reporting a problem.
Response fields
7 fieldscheckout_idAlways returnedstring (uuid)
Type: string (uuid).
deliveryAlways returnedstring
Allowed values: "sending", "sent", "failed", "uncertain".
expires_atAlways returnedinteger
Type: integer.
filer_idAlways returnedstring (uuid)
Type: string (uuid).
retry_afterAlways returnedinteger
Minimum: 0.
tax_yearAlways returnedinteger
Allowed values: 2022, 2023, 2024, 2025, 2026.
workflowAlways returnedstring
Allowed values: "efile", "tin_matching".
{
"data": {
"checkout_id": "string (uuid)",
"delivery": "string",
"expires_at": "integer",
"filer_id": "string (uuid)",
"retry_after": "integer",
"tax_year": "integer",
"workflow": "string"
},
"meta": {
"api_version": "v1",
"request_id": "string"
}
}Successful response structure. This outline shows field types, not a response to copy. Expand Response fields for nested properties and optional values.
Errors to handle
Errors use {error: {code, message}, meta}. Check the code and message before retrying. Authentication, validation and availability errors can occur before the operation runs.
- 400
invalid_request - Check required fields, selectors and supported values.
- 401
invalid_token - Obtain a valid OAuth token for this resource. Check its expiry and current authorization.
- 403
insufficient_scope - Request the listed scopes through the application's authorization flow.
- 403
forbidden - Check the connection's permissions and allowed filers. More scopes alone may not grant access.
- 404
not_found - Check the resource ID and its owning filer. Batch reads report missing IDs as documented.
- 409
conflict - Read the current state and resolve the conflict. Do not change the body under an existing idempotency key.
- 412
precondition_failed - Read the current version or preview again; a required precondition has changed.
- 422
validation_failed - Correct the reported validation issues before retrying.
- 429
rate_limited - Wait for Retry-After before retrying. Avoid concurrent retries.
- 500
internal_error - Retain request_id and retry an uncertain result with the same body and idempotency key.
- 503
service_unavailable - Retry with bounded backoff, preserving the body and idempotency key.