Orders
Preview an order
Check eligible recipients, services and current pricing before submitting an order.
/api/v1/orders/preview- Authentication
- OAuth 2.0 access token
- Required scopes
orders.preview- Idempotency key
- Not required
- Rate-limit cost
- 10 units
How to use this endpoint
A preview does not charge or submit. Review the total, funding and policy version, then pass the expected values to submit. The tax year must match the filer. State E-File is unavailable; State Reporting File and federal CF/SF remain separate services. pricing_basis describes the account's per-order or cumulative-year pricing. Cumulative pricing is the default unless staff explicitly disables it; cancelled orders do not contribute annual volume. Clients cannot set the accumulated volume.
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.
curl --request POST 'https://api.efilemagic.com/api/v1/orders/preview' \
--header 'Authorization: Bearer <access-token>' \
--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.
funding_aliasRequiredstring
Approved funding alias configured for the connection. Minimum characters: 1. Maximum characters: 64.
service_codesRequiredarray<string>
Services to include in the order. Review availability and pricing with preview first. Must include efile and e_delivery. State E-File is not currently available: new state_efile requests return HTTP 400 invalid_request with message 'State E-File is not currently available.'. State Reporting File (irs_spec_file) remains available. Historical response identities are unchanged. Minimum items: 2. Maximum items: 4. Items must be unique.
tax_yearOptionalinteger | null
Tax year of the filer and forms being processed. Allowed values: 2022, 2023, 2024, 2025, 2026.
Headers (2)
AuthorizationRequired- OAuth RS256 access token issued for the EFM API resource. Interactive EFM session tokens are rejected.
DPoPConditional / optional- Required when the application, connection, or credential is proof-of-possession bound.
curl --request POST 'https://api.efilemagic.com/api/v1/orders/preview' \
--header 'Authorization: Bearer <access-token>' \
--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.
On success, data contains the fields below. meta includes api_version and request_id. Keep request_id when reporting a problem.
Response fields
13 fieldsblocked_released_recipientsMay be omittedinteger
Minimum: 0.
blocked_tin_matched_recipientsMay be omittedinteger
Minimum: 0.
blocked_unvalidated_recipientsMay be omittedinteger
Minimum: 0.
currencyAlways returned"USD"
Value: "USD".
eligible_recipientsMay be omittedinteger
Minimum: 0.
estimated_payment_due_minorMay be omittedinteger
Minimum: 0.
expected_total_minorAlways returnedinteger
Minimum: 0.
filer_idAlways returnedstring (uuid)
Type: string (uuid).
funding_kindAlways returnedstring
Allowed values: "deposit", "terms", "vaulted_instrument".
policy_versionAlways returnedinteger
Minimum: 1.
pricing_basisMay be omittedobject
Unknown fields are rejected.
Nested fields (3)
modeAlways returnedstring
Allowed values: "per_order", "cumulative_tax_year".
starting_recipient_countAlways returnedinteger
Minimum: 0.
tax_yearAlways returnedinteger
Type: integer.
servicesAlways returnedarray<object>
Type: array<object>.
{
"data": {
"blocked_released_recipients": "integer",
"blocked_tin_matched_recipients": "integer",
"blocked_unvalidated_recipients": "integer",
"currency": "\"USD\"",
"eligible_recipients": "integer",
"estimated_payment_due_minor": "integer",
"expected_total_minor": "integer",
"filer_id": "string (uuid)",
"funding_kind": "string",
"policy_version": "integer",
"pricing_basis": "object",
"services": "array<object>",
"tax_year": "integer | null"
},
"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.