Checkout invitations
Get checkout email status
Read the delivery and expiration of a checkout email request.
/api/v1/orders/checkout/get- Authentication
- OAuth 2.0 access token
- Required scopes
orders.read- Idempotency key
- Not required
- Rate-limit cost
- 1 unit
How to use this endpoint
Use the same delegated user and connection that requested the email. The response contains no checkout token or URL. Track submitted orders with the order read endpoints. Routine OAuth token refresh does not invalidate an existing checkout email; current user, membership, connection, enrollment and policy authority are still required.
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.
Request example
curl --request POST 'https://api.efilemagic.com/api/v1/orders/checkout/get' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{"checkout_id":"11111111-1111-4111-8111-111111111111"}'Replace placeholders with your own values. Use the API resource origin provided for your environment.
Request fields
1 fieldscheckout_idRequiredstring (uuid)
Checkout request identifier returned by orders/checkout/request.
Headers (1)
AuthorizationRequired- OAuth Bearer token with the listed scopes and current resource authorization.
Request example
curl --request POST 'https://api.efilemagic.com/api/v1/orders/checkout/get' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{"checkout_id":"11111111-1111-4111-8111-111111111111"}'Replace placeholders with your own values. Use the API resource origin provided for your environment.
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.
- 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; retry with bounded backoff.
- 503
service_unavailable - Retry with bounded backoff.