Reward Order Integration REST API

```

REST services for exporting direct orders and importing order status and shipping updates.

The typical process is to query orders for export based on their status. Once an order has been imported into your system, the order is confirmed by updating its status and recording your internal order number as a reference. Storing your internal order number allows subsequent shipping updates to be processed using your internal order identifier, eliminating the need to persist the Sparc order number.

1. Export Direct Orders

This service returns a list of reward orders in the Sparc platform that are assigned to to the program codes that are included in the request along with the other filter criteria

GET
https://2039y0is59.execute-api.eu-north-1.amazonaws.com/training/cxf/integration/exportDirectOrder?accessKey={accessKey}&programCodes={programCodes}&orderStatusCode={orderStatusCode}&orderNumber={orderNumber}&remoteOrderNumber={remoteOrderNumber}&lastModifiedDateTime={lastModifiedDateTime}
Purpose
Retrieves direct orders matching the supplied search criteria.
Request body
None
Authentication
Access key supplied through the accessKey query parameter.

Query Parameters

Parameter Required Description Example
accessKey Yes Authentication key used to authorize access to the integration service. abc123xyz
programCodes Yes One or more program codes used to filter the exported orders. Multiple values must be separated by a comma. You program code values will be provided to you. PROGRAM1,PROGRAM2
orderStatusCode Yes Filters results to orders with the specified order status code. The code values for your site will be provided to you. SB
orderNumber Optional Filters results by the Sparc reward order number. OD-100245
remoteOrderNumber Optional Filters results by the order number assigned by your internal order number. This value is updated on the order by the 'Import Reward Order Status' API call. REMOTE-78452
lastModifiedDateTime Optional Filters results based on the date and time the order was last modified in the UTC timezone. Use the date-time format required by the integration service. 01/01/2024 16:35:15

Example Request

HTTP

GET 
https://2039y0is59.execute-api.eu-north-1.amazonaws.com/training/cxf/integration/exportDirectOrder?accessKey=abc123xyz&programCodes=PROGRAM1%2CPROGRAM2&orderStatusCode=SB&lastModifiedDateTime=2026-05-15 HTTP/1.1
```

Host: api.example.com
Accept: application/json
```

cURL

curl --request GET \
```

"https://2039y0is59.execute-api.eu-north-1.amazonaws.com/training/cxf/integration/exportDirectOrder?accessKey=abc123xyz&programCodes=PROGRAM1%2CPROGRAM2&orderStatusCode=SB&lastModifiedDateTime=2026-07-15" 
--header "Accept: application/json"
```

Example Successful Response

The response model below is illustrative. 
[
    {
        "accountCode": "15552258-UGG",
        "accountName": "186 MAC CORP",
        "storeCode": null,
        "customerType": null,
        "totalOrderedQty": 3,
        "promotionCode": "NCH8NG",
        "programName": "Dollar Donations",
        "hubsoftOrderNumber": "UU-701188",
        "remoteOrderNumber": "",
        "orderDateTime": "05/13/2026 14:13:49",
        "shipDate": null,
        "startDate": "05/13/2026",
        "cancelDate": "06/02/2026",
        "modifiedDateTime": "07/16/2026 23:22:07",
        "orderTypeCode": "Wholesale - US",
        "orderStatusCode": "PN",
        "orderStatusId": 140,
        "repCode": null,
        "notes": "",
        "shipToAttention": "Mike Jones",
        "shipToEmail": "info@hubsoft.com",
        "shipToPhone": "(888) 999-8989",
        "optInEmail": "N",
        "shippingAddress": {
            "name": null,
            "street1": "123 Main Street",
            "street2": "Suite 7",
            "city": "Laguna Beach",
            "stateCode": "CA",
            "countryCode": "US",
            "postalCode": "92651"
        },
        "shippingMethodCode": "000001_UPS_P_GND",
        "salesTax": 0.0,
        "freightTax": 0.0,
        "warehouseCode": null,
        "shipmentList": [
            {
                "trackingNumber": "",
                "receivedBy": "",
                "numberOfPackages": "0",
                "shipCost": 0.0,
                "shipCharged": 0.0,
                "shipOther": 0.0,
                "salesTaxAmount": 0.0,
                "shippingMethodCode": "000001_UPS_P_GND",
                "shipDate": null,
                "shippingCarrier": "UPS",
                "shippingCarrierService": "Ground Service",
                "shippedItems": null
            }
        ],
        "paymentMethodCode": "AX",
        "cardHolderFirstName": "",
        "cardHolderLastName": "",
        "cardNumber": "",
        "cardExpiryMMYYYY": "01/2026",
        "paymentReference": "",
        "paymentApprovalCode": "",
        "paymentProcessDate": null,
        "cardExpiryMonth": "01",
        "cardExpiryYear": "2026",
        "customerNumber": "",
        "billingAddress": {
            "name": null,
            "street1": "124 Main Street",
            "street2": "Suite 6",
            "city": "Laguna Beach",
            "stateCode": "CA",
            "countryCode": "US",
            "postalCode": "92651"
        },
        "orderItemList": [
            {
                "sku": "DONATE25",
                "orderedQty": 1,
                "cancelledQty": 0,
                "shippedQty": 0,
                "unitPrice": 0.0,
                "salesTax": 0.0,
                "coordinateCode": null,
                "productNumber": "DONATE",
                "sizeName": "$25",
                "productReference": "DONATIONS",
                "colorCode": "NO_COLOR",
                "colorName": "NO COLOR",
                "upc": "",
                "productName": "Donations",
                "pcscdId": 6151417,
                "caseItems": null,
                "msrp": 0.0,
                "wholesalePrice": 0.0,
                "distributionCode": null
            }
        ],
        "promotionPurchaseId": 1612,
        "shiptoAddressId": 12890346,
        "billtoAddressId": 12890347,
        "currencyCode": "USD",
        "trackingNumber": "",
        "receivedBy": "",
        "numberOfPackages": "0",
        "shipCost": 0.0,
        "shipAmount": 0.0,
        "orderedAmount": 0.0,
        "purchasePointsUsed": 0,
        "promotionTypeCode": null,
        "orderAttrList": [],
        "returns": [],
        "giftCardNumber": "",
        "giftCardAmount": 0.0,
        "giftCardPaymentReference": "",
        "giftCardPaymentApprovalCode": "",
        "giftCardPaymentProcessResult": "Pending",
        "giftCardPaymentProcessDate": null
    }
]
```

2. Import Reward Order Status

This endpoint is used to confirm the order was imported successfully into yrou system and advance the order status to exlude from future export requests. Updating the order with your internal 'remote order number' will allow the shipping update to transact using yoru internal order number.

POST
https://2039y0is59.execute-api.eu-north-1.amazonaws.com/training/cxf/cxf/integration/importDirectOrderStatus?accessKey={accessKey}&orderNumber={orderNumber}&remoteOrderNumber={remoteOrderNumber}&orderStatusCode={orderStatusCode}
Purpose
Updates the remote order number and order status for an existing direct order.
Request body
None. Request values are supplied as URL query parameters.
Authentication
Access key supplied through the accessKey query parameter.

Query Parameters

Parameter Required Description Example
accessKey Yes Authentication key used to authorize access to the integration service. abc123xyz
orderNumber Yes Sparc order number identifying the order to update. ORD-100245
remoteOrderNumber Optional Order number assigned to the order by the remote system. REMOTE-78452
orderStatusCode Yes New status code to assign to the order to acknowledge receipt and exclude it from future import calls. OP

Example Request

HTTP

POST /cxf/integration/importDirectOrderStatus?accessKey=abc123xyz&orderNumber=ORD-100245&remoteOrderNumber=REMOTE-78452&orderStatusCode=PROCESSING HTTP/1.1
```

Host: api.example.com
Accept: application/json
Content-Length: 0
```

cURL

curl --request POST \
```

"https://2039y0is59.execute-api.eu-north-1.amazonaws.com/training/cxf/integration/importDirectOrderStatus?accessKey=abc123xyz&orderNumber=ORD-100245&remoteOrderNumber=REMOTE-78452&orderStatusCode=OP" 
--header "Accept: application/json"
```

Example Successful Response

{
'``

"success": true,
}
```

Example Error Response

{
```
"success": false,
}
```

3. Import Direct Shipping Update

This endpoint allows an order to be updated to Shipped status and includes the shipment tracking number, enabling the user to view tracking information for their order.

POST
/cxf/integration/importDirectShippingUpdate?accessKey={accessKey}&orderNumber={orderNumber}&orderStatusCode={orderStatusCode}&shipDate={shipDate}&shippingMethodCode={shippingMethodCode}&trackingNumber={trackingNumber}
Purpose
Records shipment status, shipping date, shipping method, and tracking information for an existing direct order.
Request body
None. Request values are supplied as URL query parameters.
Authentication
Access key supplied through the accessKey query parameter.

Query Parameters

Parameter Required Description Example
accessKey Yes Authentication key used to authorize access to the integration service. abc123xyz
orderNumber Yes Sparc order number identifying the shipment being updated. ORD-100245
orderStatusCode Yes Status code representing the updated state of the order. SHIPPED
shipDate Yes Date on which the order was shipped. Use the date format required by the integration service. 2026-07-15
shippingMethodCode optional Code identifying the shipping carrier, service, or delivery method. UPS_GROUND
trackingNumber Optional Carrier-provided tracking number for the shipment. 1Z999AA10123456784

Example Request

HTTP

POST /cxf/integration/importDirectShippingUpdate?accessKey=abc123xyz&orderNumber=ORD-100245&orderStatusCode=SHIPPED&shipDate=2026-07-15&shippingMethodCode=UPS_GROUND&trackingNumber=1Z999AA10123456784 HTTP/1.1
```

Host: api.example.com
Accept: application/json
Content-Length: 0
```

cURL

curl --request POST \
```

"https://2039y0is59.execute-api.eu-north-1.amazonaws.com/training/cxf/integration/importDirectShippingUpdate?accessKey=abc123xyz&orderNumber=ORD-100245&orderStatusCode=SHIPPED&shipDate=2026-07-15&shippingMethodCode=UPS_GROUND&trackingNumber=1Z999AA10123456784" 
--header "Accept: application/json"
```

Example Successful Response

{
```

"success": true,
"message": "Shipping update imported successfully.",
"orderNumber": "ORD-100245",
"orderStatusCode": "SHIPPED",
"shipDate": "2026-07-15",
"shippingMethodCode": "UPS_GROUND",
"trackingNumber": "1Z999AA10123456784"
}
```

Example Error Response

{
```
"success": false,
}
```

URL Encoding

All query parameter values must be URL encoded before the request is sent. This is especially important for values containing spaces, commas, colons, ampersands, plus signs, slashes, or other reserved characters.

Original Value Encoded Value Example Parameter Notes
PROGRAM1,PROGRAM2 PROGRAM1%2CPROGRAM2 programCodes The comma is encoded as %2C.
UPS Ground UPS%20Ground shippingMethodCode The space is encoded as %20.
2026-07-15T09:30:00 2026-07-15T09%3A30%3A00 lastModifiedDateTime The colons are encoded as %3A.

HTTP Status Codes

Status Code Description
200 OK The request was accepted and processed successfully.
400 Bad Request One or more required parameters are missing, blank, incorrectly formatted, or invalid.
401 Unauthorized The access key is missing, invalid, expired, or inactive.
404 Not Found The specified order or requested service could not be found.
405 Method Not Allowed The request used an HTTP method that is not supported by the endpoint.
500 Internal Server Error The server encountered an unexpected error while processing the request.

General Validation Requirements

Security Considerations

Use HTTPS for every request. Because the access key is included in the URL, it may otherwise be exposed through network traffic, server logs, proxy logs, monitoring systems, or browser history.
```