Applying store credit
Learn how to apply store credit
For non-recurring transactions, customers can pay using store credit, a unique payment type that allows you to use the Digital River API to connect your credit management system to the checkout process. With store credit, you manage customers' credit on your end, and can display the amount available to them during the checkout.
On this page, the information in the sections on creating and applying store credit only pertains to versions 2020-09-30, 2020-12-17, and 2021-02-23.
For versions 2021-03-23 and higher, refer to the documentation on secondary payment sources. There you'll find information on how to create secondary sources, combine them with primary sources, and attach them to checkouts.
Whether an order is paid for with store credit, a primary payment source, or a combination of the two, the steps necessary to handle fulfillments and request refunds remain the same. However, when combining store credit with a primary payment source, you should be aware of how we handle captures, cancels, and refunds.

Creating store credit

In a POST/checkouts or POST/checkouts/{id}, you can use creditAmount to simultaneously create and apply store credit. In the request, creditAmount represents the amount of store credit you're extending to the customer.
Store credit is a single-use payment source.

Handling multiple lines of credit

During the checkout process, you can only send creditAmount once. If you pass creditAmount in a create or update checkout request and then attempt to pass more creditAmount in a subsequent update checkout request, you receive the following error:
409 Conflict
1
{
2
"type": "conflict",
3
"errors": [
4
{
5
"code": "creditAmount_already_updated",
6
"message": "Credit amount has already been updated."
7
}
8
]
9
}
Copied!
So, when customers have multiple lines of credit that they want to apply to a checkout, you should aggregate them and send creditAmount in a single request.

How store credit is represented in the checkout

When you create store credit, the checkout's sources array will contain a source with a type of customerCredit.
If you use store credit alone, this will be the only payment source in the array. If you pair store credit with another payment source, then the array will also contain a primary source object.
Checkout response with customerCredit
1
{
2
"id": "ef285ef9-8bf8-4589-9eeb-2cabe5ac2f2b",
3
...
4
"billTo": {
5
"address": {
6
"line1": "434 3rd Street",
7
"city": "Minneapolis",
8
"postalCode": "55401",
9
"state": "MN",
10
"country": "US"
11
},
12
"name": "John Doe",
13
"phone": "952-111-1111",
14
"email": "[email protected]"
15
},
16
"totalAmount": 5.0,
17
"subtotal": 5.0,
18
...
19
"items": [
20
{
21
"id": "4ee416f5-4d52-4f3f-8474-266212cef9a9",
22
"skuId": "6cc49812-965d-493a-8048-e8c70397c08e",
23
"amount": 5.0,
24
"quantity": 1,
25
...
26
],
27
"creditAmount": 10.0,
28
"sources": [
29
{
30
"id": "f9b80c8f-07fd-4b2d-8c64-eea729712fc2",
31
"createdTime": "2021-03-08T20:47:07Z",
32
"type": "customerCredit",
33
"currency": "USD",
34
"amount": 5.0,
35
"reusable": false,
36
"state": "consumed",
37
"owner": {
38
"firstName": "John",
39
"lastName": "Doe",
40
"email": "[email protected]",
41
"address": {
42
"line1": "434 3rd Street",
43
"city": "Minneapolis",
44
"postalCode": "55401",
45
"state": "MN",
46
"country": "US"
47
}
48
},
49
"clientSecret": "f9b80c8f-07fd-4b2d-8c64-eea729712fc2_d2829190-fd91-4455-8851-8b2e27affd54",
50
"customerCredit": {}
51
}
52
],
53
"sourceId": "f9b80c8f-07fd-4b2d-8c64-eea729712fc2"
54
}
Copied!

Applying store credit

The process of creating store credit automatically applies it to a checkout. You can then use it as a stand-alone payment source or pair it with a primary payment source. In either case, Digital River first computes taxes based on the full order value, and then applies the store credit.

Using store credit alone

A customer can conduct a transaction entirely with store credit. To do so, the amount of created store credit must be equal to or greater than the checkout's totalAmount before you convert it to an order. In this scenario, you're not required to pair store credit with a primary payment source.
However, when using store credit alone, you must set the checkout's billTo. If you don't, you'll receive a 409 Conflict when you convert the checkout to an order.

Pairing store credit with a primary payment source

If the amount of created store credit is less than the checkout's totalAmount, then you need to attach a primary payment source prior to order submission. If you don't do this, when you convert the checkout to an order, you receive the following error:
400 Bad Request
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "order_submit_failed",
6
"message": "Payment session status is invalid."
7
}
8
]
9
}
Copied!
For a list of primary sources that can be combined with customerCredit, refer to combining payment sources on the Managing sources page.
During the checkout process, how you sequence the application of store credit with a primary source depends on whether or not the primary source is saved to the customer's record.
If both customerCredit and a primary payment source are contained in the checkout's sources array, you can replace the primary source with a different primary source by sending its sourceId in the payload of aPOST/checkouts/{id}.

Unsaved primary sources

When the primary source is not saved to the customer's record, you must first apply the store credit before attaching the primary source. In other words, you first specify a creditAmount in a create or update checkout request. Then, if the amount of customerCredit in the sources array is less than the checkout's totalAmount, you must update that checkout with a primary source.
If your workflow first attaches an unsaved primary payment source, and then attempts to send creditAmount in a subsequent update checkout request, you'll receive the following 409 Conflict:
409 Conflict
1
{
2
"type": "conflict",
3
"errors": [
4
{
5
"code": "source_not_supported",
6
"parameter": "sourceId",
7
"message": "The source status is invalid for this session."
8
}
9
]
10
}
Copied!

Saved primary sources

When the primary source is saved to the customer's record, it doesn't matter how you sequence the application of a primary source with store credit. In other words, your workflow can apply store credit before or after the primary source is attached.

How store credit is represented in the order

When a checkout only contains store credit, and then you convert it to an order, a single charge object is generated from the customerCredit payment source.
However, the following POST/orders response shows how two charges, both in a capturable state, are created when you convert a checkout to an order and that checkout uses store credit paired with a primary source. The first charge is generated from the customerCredit payment source. The second charge is created from the supplemental creditCard.
POST/orders response
1
{
2
"id": "185314800336",
3
"customerId": "529458270336",
4
...
5
"totalAmount": 21.51,
6
"subtotal": 20.0,
7
...
8
"totalTax": 1.51,
9
...
10
"totalShipping": 5.0,
11
"items": [
12
{
13
"id": "106480520336",
14
"skuId": "6b04ac06-0858-456c-90aa-235772dea9e2",
15
"amount": 15.0,
16
"quantity": 1,
17
...
18
}
19
],
20
...
21
"creditAmount": 10.0,
22
"sources": [
23
{
24
"id": "f04ac3b4-016a-4c75-a093-20115bd27b5b",
25
...
26
"type": "creditCard",
27
...
28
"amount": 21.51,
29
"reusable": true,
30
"state": "chargeable",
31
...
32
"creditCard": {
33
"brand": "Visa",
34
"expirationMonth": 7,
35
"expirationYear": 2027,
36
"lastFourDigits": "1111"
37
}
38
},
39
{
40
"id": "3066c73f-0894-44ee-8ae6-4cd8be32642e",
41
...
42
"type": "customerCredit",
43
...
44
"amount": 10.0,
45
"reusable": false,
46
"state": "consumed",
47
...
48
"customerCredit": {}
49
}
50
],
51
...
52
"charges": [
53
{
54
"id": "aa747a62-6b56-4053-a2b7-a89fccb38389",
55
...
56
"amount": 10.0,
57
"state": "capturable",
58
...
59
"sourceId": "3066c73f-0894-44ee-8ae6-4cd8be32642e",
60
...
61
},
62
{
63
"id": "2ad942b5-6e47-40ca-b991-9bbd02b36a44",
64
...
65
"amount": 11.51,
66
"state": "capturable",
67
...
68
"sourceId": "f04ac3b4-016a-4c75-a093-20115bd27b5b",
69
...
70
}
71
],
72
...
73
"checkoutId": "afb203a4-6ca8-4748-9450-4586969a17ca"
74
}
Copied!

How we handle captures, cancels, and refunds

When combining store credit with a primary payment source, you should be aware of the logic we use to capture charges, cancel charges and process refunds.

How we capture store credit

When you notify us that an order is partially or completely fulfilled, we attempt to capture the charge created from customerCredit before capturing the charge generated from the primary payment source (if it exists).
The following example order demonstrates this concept. The order contains a single line item with a quantity of 2. The totalAmount of the order is 26.89 . The order was created with a creditAmount of 11.0 dollars and a supplemental credit card to cover the shortfall. As a result, two charge objects are contained in the charges array.
So, in this example, when a client system sends a POST/fulfillments request with a quantity of 1 in the payload, thereby notifying us that the order was partially fulfilled, we completely capture the charge amount created from the customerCredit source and move that charge into a complete state. This causes an order.charge.complete event to fire.
But, since not enough of the order was fulfilled to completely capture both charges, the charge amount created from the creditCard is only partially captured, and that charge remains in a capturable state.
Order
1
{
2
"id": "185326550336",
3
...
4
"totalAmount": 26.89,
5
"subtotal": 25.0,
6
"totalTax": 1.89,
7
...
8
"items": [
9
{
10
"id": "106494910336",
11
"skuId": "6b04ac06-0858-456c-90aa-235772dea9e2",
12
"amount": 20.0,
13
"quantity": 2,
14
...
15
}
16
],
17
...
18
"creditAmount": 11.0,
19
"sources": [
20
{
21
"id": "21216ef6-d153-445a-8c81-3d912dfcf63a",
22
...
23
"type": "customerCredit",
24
...
25
"amount": 11.0,
26
...
27
"customerCredit": {}
28
},
29
{
30
"id": "10103f7f-ce6f-47f2-b064-47931779ebea",
31
...
32
"type": "creditCard",
33
...
34
"amount": 15.89,
35
...
36
"paymentSessionId": "cac4fac7-8c54-46d8-86b1-c595a963d719",
37
...
38
"creditCard": {
39
"brand": "Visa",
40
"expirationMonth": 7,
41
"expirationYear": 2027,
42
"lastFourDigits": "1111"
43
}
44
}
45
],
46
...
47
"charges": [
48
{
49
"id": "84cdf3e6-f70e-49ca-8847-248d039f66d9",
50
...
51
"amount": 11.0,
52
"state": "complete",
53
"captured": true,
54
"captures": [
55
{
56
"id": "a57b0805-4b57-46ec-a963-124ada0b536a",
57
"createdTime": "2021-03-08T21:14:51Z",
58
"amount": 11.0,
59
"state": "complete"
60
}
61
],
62
...
63
"sourceId": "21216ef6-d153-445a-8c81-3d912dfcf63a",
64
...
65
},
66
{
67
"id": "60bbc0e7-affc-46ed-a3e8-3171d4de01cb",
68
...
69
"amount": 15.89,
70
"state": "capturable",
71
"captured": true,
72
"captures": [
73
{
74
"id": "42253229-ad78-4c64-8096-9bb4138b4433",
75
"createdTime": "2021-03-08T21:14:51Z",
76
"amount": 2.45,
77
"state": "complete"
78
}
79
],
80
...
81
"sourceId": "10103f7f-ce6f-47f2-b064-47931779ebea",
82
...
83
}
84
],
85
...
86
"checkoutId": "9d92cc87-0e22-4dbe-bc76-e9d8eba1435f"
87
}
Copied!

How we cancel store credit

When you notify us that an order is partially or completely cancelled, we cancel the charge created from the primary payment source (if it exists) before cancelling the charge generated from the customerCredit.
The following example order demonstrates this concept. The order contains a single digital line item with a quantity of 2. The totalAmount of the order is 20.0 . The order was created with a creditAmount of 5.0 dollars and a supplemental credit card to cover the shortfall. As a result, two charge objects are contained in the charges array.
So, in this example, when a client system sends a POST/fulfillments request with a cancelQuantity of 1, we partially cancel the charge amount created from the creditCard payment source. No cancels have yet been performed on the charge generated from the customerCredit.
Order
1
{
2
"id": "186017330336",
3
...
4
"totalAmount": 20.0,
5
"subtotal": 20.0,
6
"totalTax": 0.0,
7
...
8
"items": [
9
{
10
"id": "107253530336",
11
"skuId": "c59bc37a-1351-4efe-939a-7f15381ed905",
12
"amount": 20.0,
13
"quantity": 2,
14
...
15
}
16
],
17
...
18
"creditAmount": 5.0
19
"sources": [
20
{
21
"id": "9110f993-075c-446b-a557-858adce4463e",
22
"type": "creditCard",
23
"amount": 15.0,
24
...
25
"creditCard": {
26
"brand": "Visa",
27
"expirationMonth": 7,
28
"expirationYear": 2027,
29
"lastFourDigits": "1111"
30
}
31
},
32
{
33
"id": "221e9fa6-2cdb-4bda-aaf4-1c6edb185441",
34
"type": "customerCredit",
35
"amount": 5.0,
36
"customerCredit": {}
37
}
38
],
39
"charges": [
40
{
41
"id": "0d08d450-3c87-4456-9900-5c7e2009d7ce",
42
...
43
"amount": 15.0,
44
"state": "capturable",
45
"captured": false,
46
"refunded": false,
47
"cancels": [
48
{
49
"id": "c92fc885-d53b-42ba-ba5a-7a32a9e5f6d2",
50
"createdTime": "2021-03-18T20:27:20Z",
51
"amount": 10.0,
52
"state": "complete"
53
}
54
],
55
"sourceId": "9110f993-075c-446b-a557-858adce4463e",
56
...
57
},
58
{
59
"id": "15f0f926-206a-4843-a96f-2fb07bc44087",
60
...
61
"amount": 5.0,
62
"state": "capturable",
63
"captured": false,
64
"refunded": false,
65
"sourceId": "221e9fa6-2cdb-4bda-aaf4-1c6edb185441",
66
...
67
}
68
],
69
...
70
}
Copied!

How we refund store credit

When you issue a refund on an order that uses store credit, the refund is first applied to the primary payment source (if it exists) and then the store credit.
The following example order demonstrates this concept. The order was placed using store credit and a supplemental credit card. It was completely fulfilled, meaning both charges were fully captured and moved into a complete state.
After being fulfilled, the client system submitted an order-level refund of 50 percent.
Notice that the credit card is fully refunded. However, the customerCredit is only partially refunded. This means that in any subsequent refund requests, the remaining availableToRefundAmount will be issued to the customerCredit.
Order with partial refund
1
{
2
"id": "185317330336",
3
...
4
"totalAmount": 26.89,
5
"subtotal": 25.0,
6
...
7
"totalTax": 1.89,
8
...
9
"totalShipping": 5.0,
10
"items": [
11
{
12
"id": "106484310336",
13
"skuId": "6b04ac06-0858-456c-90aa-235772dea9e2",
14
"amount": 20.0,
15
"quantity": 2,
16
...
17
"tax": {
18
"rate": 0.07525,
19
"amount": 1.51
20
...
21
"availableToRefundAmount": 13.44,
22
...
23
}
24
],
25
...
26
"creditAmount": 20.0,
27
"sources": [
28
{
29
"id": "b77fec60-590b-4330-8d6b-bb069cf5545e",
30
...
31
"type": "customerCredit",
32
...
33
"amount": 20.0,
34
...
35
"state": "consumed",
36
...
37
"customerCredit": {}
38
},
39
{
40
"id": "b73d759c-eff0-4327-960f-75b86dd87764",
41
...
42
"type": "creditCard",
43
...
44
"amount": 6.89,
45
...
46
"state": "consumed",
47
...
48
"creditCard": {
49
"brand": "Visa",
50
"expirationMonth": 7,
51
"expirationYear": 2027,
52
"lastFourDigits": "1111"
53
}
54
}
55
],
56
"refundedAmount": 13.45,
57
"state": "complete",
58
...
59
"charges": [
60
{
61
"id": "b80d59ee-546d-4f04-8fc9-8c4f630594aa",
62
...
63
"amount": 20.0,
64
"state": "complete",
65
"captured": true,
66
"captures": [
67
{
68
"id": "012d0a54-8e34-48a5-b5e0-5d6735901d95",
69
"createdTime": "2021-03-08T20:01:34Z",
70
"amount": 20.0,
71
"state": "complete"
72
}
73
],
74
"refunded": true,
75
"refunds": [
76
{
77
"createdTime": "2021-03-08T20:06:44Z",
78
"amount": 6.56,
79
"state": "complete"
80
}
81
],
82
"sourceId": "b77fec60-590b-4330-8d6b-bb069cf5545e",
83
...
84
},
85
{
86
"id": "c7464db6-33c8-45f6-9cb6-4fa5a2a658c9",
87
...
88
"amount": 6.89,
89
"state": "complete",
90
"captured": true,
91
"captures": [
92
{
93
"id": "191c66ac-7713-49f3-a605-ec9fae84fbf9",
94
"createdTime": "2021-03-08T20:01:34Z",
95
"amount": 6.89,
96
"state": "complete"
97
}
98
],
99
"refunded": true,
100
"refunds": [
101
{
102
"createdTime": "2021-03-08T20:06:44Z",
103
"amount": 6.89,
104
"state": "complete"
105
}
106
],
107
"sourceId": "b73d759c-eff0-4327-960f-75b86dd87764",
108
...
109
}
110
],
111
...
112
"capturedAmount": 26.89,
113
...
114
"availableToRefundAmount": 13.44,
115
"checkoutId": "dc16d13b-d379-45bc-9be1-f3bd798410d2"
116
}
Copied!
Last modified 3mo ago