Reference

Field Glossary

Shared field meanings used across Merchant API workflows.

This page is a glossary, not a replacement for workflow pages or OpenAPI schemas. Use it to understand repeated field names and identifiers. Use each workflow page for request/response examples, and use OpenAPI for the exact machine-readable contract.

Identifiers

Field	Meaning
`order_id`	FutureSMS business order identifier. Store it after send or bulk execution and use it for direct order lookups.
`client_order_id`	Optional merchant-side reference supplied on single SMS send. It is unique for the merchant and helps with reconciliation after timeouts.
`bulk_job_id`	FutureSMS identifier for a bulk upload job. It groups uploaded CSV rows and execution state.
`bulk_job_item_id`	FutureSMS identifier for one row inside a bulk job. Use it when investigating row-level outcomes.
`template_id`	Approved template logical identifier. The selected template controls how `var` is interpreted.
`sender_id`	Sender selector used in API requests. Use an authorized `SID-...` value, or `AUTO` when FutureSMS has enabled auto routing for the merchant.
`sender_value`	Sender value actually used for the message after sender selection is resolved, as returned on order reads.
`merchant_id`	FutureSMS merchant account identifier. Merchant API users normally see only their own merchant context.
`user_id`	FutureSMS user identifier associated with an action or resource when exposed.

Message Content

Field	Meaning
`phone_number`	Destination phone number. Messaging endpoints expect E.164-style values, for example `+639171234567`.
`var`	Optional template variable value. It is interpreted by the selected template, not by a global message format.
`content`	Rendered message content returned by tracking endpoints.
`dlr_address`	Delivery report callback URL used for the order when one is configured or overridden.
`dlr_available`	Whether delivery report information is available for the order.

Bulk Counts

Field	Meaning
`total_rows`	Number of data rows read from the uploaded CSV.
`valid_rows`	Rows accepted during upload itemization.
`invalid_rows`	Rows rejected during upload itemization.
`ordered_rows`	Rows that produced SMS orders during execution.
`row_no`	1-based row number from the uploaded CSV data rows.
`error_message`	Row-level rejection reason for a bulk item. It belongs to that row, not to the whole API response envelope.

Status Fields

Field	Meaning
`order_status`	Business order processing and billing state.
`message_status`	Normalized delivery state when delivery information is available.
`bulk_job_status`	Job-level state for a bulk upload and execution workflow.
`bulk_item_status`	Row-level state inside a bulk job.

Status values are listed on Status Values. Workflow pages explain what each value means in that workflow.

Time Fields

Field	Meaning
`created_at`	When the resource or event was first recorded.
`updated_at`	When the resource was last changed.
`started_at`	When an asynchronous job or process began.
`completed_at`	When an asynchronous job or process finished.

All API timestamps use UTC with a Z suffix. See Date and Time for timestamp and range-filter rules.

Auth Fields

Field	Meaning
`access_token`	Bearer token used for authenticated Merchant API requests.
`refresh_token`	Token used to obtain a new access token through the refresh flow.
`token_type`	Token scheme, usually `bearer`.
`access_token_expires_at`	UTC expiry time for the access token.
`refresh_token_expires_at`	UTC expiry time for the refresh token.
`username`	Authenticated username.
`role`	User role. See `UserRoleEnum` on Status Values.

Amounts

Field	Meaning
`merchant_price_usd`	Merchant-facing order price in USD, returned as a decimal string.
`merchant_prepaid_cash`	Merchant prepaid balance as a decimal string when profile data includes it.
`merchant_credit_available`	Merchant available credit as a decimal string when profile data includes it.

Amounts are strings in JSON where precision matters. Do not parse them as floating-point values in billing-sensitive code.

Yeastar P-Series

Configure Yeastar P-Series to send SMS through FutureSMS-compatible endpoints.

Status Values

Shared status and role values used across Merchant API workflows.