State Data

Methods

The state data is a simple key-value store that is unique to your merchant account. You can set a piece of data using state.set and later retrieve it using state.get. The data is stored and returned as a string but you could serialize your data using any serialization method you like.

This feature is intended to be used sparingly, such as to store a timestamp of the last time a synchronization occurred, or as a locking mechanism to prevent two processes from conflicting. It is **not** intended to be used to store state information for every order.

Limits

`state` length 255 bytes
`value` length 2 kilobytes
number of keys TBD

State Properties

state 
{ "state" : "foo" }
The "key" which is used to identify the state data.
value 
{ "value" : "bar" }
The state data.
updated_at 
{ "updated_at" : "2017-03-24 16:43:11" }
Datetime in UTC timezone when the state was inserted or updated. Optional. Returned when $detailed paramenter is true.
update_count 
{ "update_count" : 0 }
Count of the state value updates. After inserting a new state "update_count" equals to "0". Optional. Returned when $detailed paramenter is true.

state.get (string|array $keys, boolean $detailed = false)

Get one or more state data values.

Parameters

order description
0 A string to get a single key, or an array of keys to get multiple keys in one request.
1 Flag that indicates if detailed state information is needed.

Return Value

If the request parameter was a string the return value will be a JSON data type which contains the value that was previously set or null if no value was previously set.

If the request parameter was an array of keys the return value will be an object of key-value pairs.

Example Request

Get only state value:

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "state.get",
        "foo"
    ]
}

Get detailed state information:

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "state.get",
        "foo",
	true
    ]
}

Example Response

State value:

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "result" : "bar"
}

Detailed state information:

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "result" : { "value": "bar", "updated_at" : "2017-03-24 17:08:15", "update_count" : 5 }
}

state.set (string|array $keys, mixed $data = null, int|string|null $ifEquals = null)

Add or update a one or more state data values.

Parameters

order description
0 A string to set a single key, or an array of key-value pairs to set multiple keys in one request.
1 If parameter 0 is a string, the value to store for the given key.
2 If specified, the state value is only updated if the state value was previously equal to $ifEquals value

Return Value

The return value is true when at least one value was updated.

Example Request

Set a single value:

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "state.set",
        "foo",
        "bar",
	"baz"
    ]
}

Set multiple values:

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "state.set",
        {
            "foo" : "bar",
            "foo2" : "bar2"
        }
    ]
}

Example Response

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "result" : true
}