Create a store

POST api/stores

Creates a store.

Request syntax

post api/stores '{"store_name":"<store-name>","store_number":"<store-number>","address1":"<store-address>","city":"<store-city>","state":"<store-state>","zip":"<store-zipcode>","country":"<store-country>"}'

Request parameters

The request accepts the following data in JSON format.

Parameter	Type	Description	Required
`store_number`	String	The store number. It can include leading zeros, for example `0001`. Together with `store_name`, it uniquely identifies the store.	Yes
`store_name`	String	The name of the store.	Yes
`address1`	String	The first line of the physical address of the store.	Yes
`address2`	String	The second line of the physical address of the store, such as a suite or unit number.	No
`city`	String	The city of the physical address of the store.	Yes
`state`	String	The state of the physical address of the store.	Yes
`zip`	String	The zip code of the physical address of the store, as 5 digits or 9 digits, for example `78731` or `78731-1234`.	Yes
`country`	String	The country of the physical address of the store.	Yes
`phone_number`	String	The phone number of the store, for example `512-555-0100`.	No
`timezone`	String	The timezone of the store, for example `Eastern Standard Time`.	No
`group`	String	The store group that the store belongs to.	No
`level_of_hierarchy`	String	The level of hierarchy that the store is assigned to, for example `USA > NE > New York`.	No
`card_acceptor_identifier`	String	Required only if the ETL feature is enabled for the customer. The value must then be unique for the customer and is returned in the response. If the ETL feature is disabled, don't include this parameter in the request.	No

Payment configuration fields

The following optional fields set the store's payment configuration. These fields aren't returned in store responses.

SC//Reliant™ Platform Manager uses these values to build the store's payment server configuration files from configuration templates. Each value is available in templates through the template tag listed in the table. A value can be used in templates only when the matching payment integration (AJB FIPay or eSocket) is enabled for the site, and the field is selected on the matching payment configuration tab of the global store settings.

AJB FIPay fields

Parameter	Type	Description	Template tag	Required
`host_processor`	String	The host processor in the store's payment configuration.	`{{store.host_processor}}`	No
`gift_card_merchant_number`	String	The gift card (stored value) merchant ID in the store's payment configuration.	`{{store.gift_merchant_id}}`	No
`vxn_merchant_id`	String	The store's VXN merchant ID (MID).	`{{store.vxn_merchant_id}}`	No
`merchant_terminal_id`	String	The merchant terminal ID (TID) in the store's payment configuration.	`{{store.merchant_tid}}`	No
`payment_switch_1_ip`	String	The IP address of the primary payment switch. If this value is blank, the store uses a direct-to-bank template.	`{{store.payment_switch_1_ip}}`	No
`payment_switch_2_ip`	String	The IP address of the secondary payment switch.	`{{store.payment_switch_2_ip}}`	No
`payment_switch_1_certificate_name`	String	The name of the certificate used for the primary payment switch.	—	No
`payment_switch_2_certificate_name`	String	The name of the certificate used for the secondary payment switch.	—	No
`bank_processor_url_1`	String	The primary bank processor URL (the primary VXN SDC URL).	`{{store.bank_processor_url_1}}`	No
`bank_processor_url_2`	String	The secondary bank processor URL (the secondary VXN SDC URL).	`{{store.bank_processor_url_2}}`	No
`stored_value_processor_url_1`	String	The primary stored value (gift card) processor URL.	`{{store.stored_value_processor_url_1}}`	No
`stored_value_processor_url_2`	String	The secondary stored value (gift card) processor URL.	`{{store.stored_value_processor_url_2}}`	No
`dcc_functionality_enabled`	String	Whether Dynamic Currency Conversion (DCC) is enabled for the store, for example `ENABLED`.	`{{store.dcc_functionality}}`	No
`dcc_functionality_value`	String	The DCC functionality value.	—	No

eSocket fields

Parameter	Type	Description	Template tag	Required
`config_server_ip_address`	String	The IP address of the eSocket configuration server.	`{{store.configserverip}}`	No
`config_server_port`	String	The port of the eSocket configuration server.	`{{store.configserverport}}`	No
`itk_fixed_node_port`	String	The eSocket ITK fixed node port.	`{{store.itkfixednodeport}}`	No
`itk_variable_node_port`	String	The eSocket ITK variable node port.	`{{store.itkvarnodeport}}`	No
`pincomm_prompt_debit`	String	The eSocket PINComm prompt debit setting.	`{{store.pincommpromptdebit}}`	No
`ubl_lcr_threshold`	String	The eSocket UBL LCR threshold.	`{{store.ubllcrthreshold}}`	No

Response syntax

{
    "exporter_job": integer,
    "id": integer,
    "store_number": "string",
    "store_name": "string",
    "hostname": "string",
    "group": "string",
    "owner_name": "string",
    "level_of_hierarchy": "string",
    "card_acceptor_identifier": "string",
    "created_at": "timestamp",
    "updated_at": "timestamp"
}

Response parameters

If the action is successful, an HTTP 201 response is returned. The following data is returned in JSON format.

Field	Type	Description
`exporter_job`	Integer	The ID of the exporter job performing the action.
`id`	Integer	The store ID.
`store_number`	String	The store number.
`store_name`	String	The store name.
`hostname`	String	The hostname of the node or server that manages the store, for example `pfc2324pay0`. Empty if no host is assigned.
`group`	String	The store group, for example `US_ENGAGE`.
`owner_name`	String	A display name generated from the store number, city, and state, for example `Store: 9901 (Austin/TX)`.
`level_of_hierarchy`	String	The level of hierarchy the store is assigned to, for example `United States > NE > NJ`. `null` if the store isn't assigned to a level of hierarchy.
`card_acceptor_identifier`	String	The card acceptor identifier for the store.
`created_at`	Timestamp	The timestamp for when the store was initially created.
`updated_at`	Timestamp	The timestamp indicating when the store was last updated.

Errors

The following are common errors returned by this API.

Code	Message	Cause
422	Card acceptor identifier already in use. Please use a different value.	Another store already uses the `card_acceptor_identifier`.
422	Validation Failed: city is missing, country is missing, state is missing, zip is missing	One or more required parameters are missing. The message lists each missing parameter.

Examples

Example: Create a store

This example creates a store named Docs Test Store with store number 9901, a physical address, and a card acceptor identifier.

ruby api.rb <customer_code> post api/stores '{"store_name":"Docs Test Store","store_number":"9901","address1":"123 Test Way","city":"Austin","state":"TX","zip":"78731","country":"US","card_acceptor_identifier":"DOCS9901"}'

Response

{
  "exporter_job": 1781612,
  "id": 25651,
  "store_number": "9901",
  "store_name": "Docs Test Store",
  "hostname": "",
  "group": null,
  "owner_name": "Store: 9901 (Austin/TX)",
  "level_of_hierarchy": null,
  "card_acceptor_identifier": "DOCS9901",
  "created_at": "2026-10-10T17:36:20.630Z",
  "updated_at": "2026-10-10T17:36:20.630Z"
}