You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: "Manage a customer's subscription and retrieve their subscription history and information.\n
5
+
6
+
Use the provided API to enroll an end-user into a subscription plan, manage their payment method and subscription lifecycle.\n
7
+
8
+
**Onboarding**\n
9
+
10
+
If you wish to enroll an end-user into an existing subscrtipion program, there is no additional onboarding needed; simply start using these APIs.\n
11
+
12
+
If you wish to enroll an end-user into a new subscription program outside of Price Match (BPme US), Coffee Club (BPme UK) or Daily Coffee (ampm), please contact the subscritpion team. At the moment consumers are not able to self-service to create new subscription plans.\n
13
+
14
+
**Right to be forgotten & refunds**\n
15
+
16
+
Administrative features are currently only accessible by the subscription team. For requests such as to carry out a user's right to be forgotten or issuing refunds, please contact the subscription team.\n
17
+
18
+
19
+
**Payment method & integration with the user's stored wallet**\n
20
+
21
+
The subscritpion service _is not integrated_ with bp wallet at this time. Consumers will need to integrate directly with Braintree to capture the card used for the subscription payments.\n
22
+
23
+
_Note: Consumers web interfaces may need to be PCI compliant_ \n
24
+
25
+
**Interacting with API**\n
26
+
27
+
_User_\n
28
+
29
+
For retrieving information about a user's subscribscriptions - both current and past.\n
30
+
31
+
_Subscriptions_\n
32
+
33
+
For enrolling a user in a subsription plan, canceling an existing subscrption, or retrieve a user's payment method information and update a user's payment method.\n
34
+
35
+
36
+
**Contact information**\n
37
+
38
+
Product owner: Eric Doornbos (eric.doornbos@bp.com)\n
description: Enroll or manage subscription details
68
+
paths:
69
+
/user/subscriptions:
70
+
get:
71
+
tags:
72
+
- "user"
73
+
summary: "Get all subscription for the user"
74
+
description: "Returns the list of subscriptions, past and present, for that user. Only subscriptions under the provided loyalty program will be returned."
75
+
parameters:
76
+
- name: "x-loyalty-program"
77
+
in: header
78
+
schema:
79
+
$ref: "#/components/schemas/LoyaltyProgram"
80
+
responses:
81
+
'200':
82
+
description: "Successfully retrieved the subscriber's past subscriptions"
83
+
content:
84
+
application/json:
85
+
schema:
86
+
type: array
87
+
items:
88
+
$ref: '#/components/schemas/Subscription'
89
+
'404':
90
+
description: "The user was never a subscriber and has no subscriptions"
91
+
content: {}
92
+
'400':
93
+
description: "The request contains invalid parameters. Please ensure that the loyalty program plan name is correct."
94
+
content:
95
+
application/json:
96
+
schema:
97
+
type: object
98
+
properties:
99
+
error:
100
+
type: string
101
+
description: The error description
102
+
example: "X-LOYALTY-PROGRAM: my-fake-program is not a valid program"
103
+
'401':
104
+
description: "The request is missing authorization details. Please check to see if the end user JWT is provided in the header."
105
+
content: {}
106
+
'403':
107
+
description: "The request has a malformed or expired end user JWT."
108
+
content: {}
109
+
/subscriptions:
110
+
post:
111
+
summary: "Enroll the user to a subscription plan"
112
+
description: "Note:\n
113
+
114
+
Only credit and debit cards are valid payment methods for a subscription. Prepaid cards, Apple Pay and Google Wallet are not currently accepted.\n
115
+
116
+
Payment methods are not integrated with BP Wallet; consumers must generate the nonce (one-time use tokens) through Braintree."
117
+
tags:
118
+
- subscriptions
119
+
parameters:
120
+
- name: "x-loyalty-program"
121
+
in: header
122
+
schema:
123
+
$ref: "#/components/schemas/LoyaltyProgram"
124
+
requestBody:
125
+
content:
126
+
application/json:
127
+
schema:
128
+
type: object
129
+
properties:
130
+
selectedPlan:
131
+
type: string
132
+
description: The plan to enroll in. For UK Coffee Club subscriptions, please use 'HotDrinks'
133
+
enum:
134
+
- PriceMatch
135
+
- CoffeeSubscription
136
+
- HotDrinks
137
+
nonce:
138
+
type: string
139
+
description: The one time use token issued by Braintree for the payment method.
140
+
example: "fake-valid-nonce"
141
+
responses:
142
+
'201':
143
+
description: "Subscriber successfully enrolled"
144
+
'400':
145
+
description: "The requests is invalid due to missing or incorrect inputs."
146
+
content:
147
+
application/json:
148
+
schema:
149
+
type: object
150
+
properties:
151
+
error:
152
+
type: string
153
+
description: The error description
154
+
examples:
155
+
Bad loyalty program:
156
+
value: { error: "X-LOYALTY-PROGRAM: my-unicorn-program is not a valid program" }
157
+
Bad subscription plan:
158
+
value: { error: "Selected Plan: my-unicorn-plan is not a valid plan" }
159
+
'403':
160
+
description: "Attempted to complete an action that is not allowed.\n
161
+
162
+
Please check to see if the the supplied end-user JWT is valid, or if the the enrolled subscription plan is under the specified loyalty program."
163
+
content:
164
+
application/json:
165
+
schema:
166
+
type: object
167
+
properties:
168
+
error:
169
+
type: string
170
+
description: The error description
171
+
examples:
172
+
Invalid JWT:
173
+
value: {}
174
+
Mismatch between selected plan and loyalty program:
175
+
value: { error: "Selected Plan: CoffeeSubscription is not part of the users loyalty program" }
176
+
User already enrolled to another program:
177
+
value: { error: "User already has an active subscription in the specified loyalty program" }
178
+
'409':
179
+
description: "There was a conflict enrolling the user; the user is already enrolled to the selected plan"
180
+
content:
181
+
application/json:
182
+
schema:
183
+
type: object
184
+
properties:
185
+
error:
186
+
type: string
187
+
description: The error description
188
+
example: "User is already enrolled in the requested subscription"
189
+
/subscriptions/{subscriptionId}/payment:
190
+
parameters:
191
+
- name: subscriptionId
192
+
in: path
193
+
description: Subscription id to retrieve payment information fo
194
+
required: true
195
+
schema:
196
+
type: string
197
+
format: uuid
198
+
- name: "x-loyalty-program"
199
+
in: header
200
+
schema:
201
+
$ref: "#/components/schemas/LoyaltyProgram"
202
+
get:
203
+
summary: "Retrieve the payment details for a subscription"
204
+
description: "Returns the card information for the subscription."
205
+
tags:
206
+
- subscriptions
207
+
responses:
208
+
'200':
209
+
description: "Successfully retrieved the payment detail"
210
+
content:
211
+
application/json:
212
+
schema:
213
+
type: object
214
+
properties:
215
+
cardType:
216
+
type: string
217
+
description: "The credit card type"
218
+
example: Visa
219
+
expirationDate:
220
+
type: string
221
+
example: 07/21
222
+
description: "The expiration date of the credit card"
223
+
lastFourDigits:
224
+
type: string
225
+
example: "1134"
226
+
description: "The last 4 digits on the credit card"
227
+
'404':
228
+
description: "The subscription cannot be found"
229
+
'401':
230
+
description: "The request is missing the authorization key"
231
+
content: {}
232
+
'403':
233
+
description: "The request has a malformed or expired authorization key"
234
+
content: {}
235
+
'500':
236
+
description: "An unknown exception has occured; consumer should contact the subscription team to resolve this."
237
+
put:
238
+
summary: "Update the card to use subscription recurring charges."
239
+
description: "New payment method will be effective immediately. \n
240
+
241
+
If a user's account is past due, it will be charged immediately. Otherwise, the card will be charged on the next billing date. Only the payment methods types allowed during enrollment is allowed when updating payment methods."
242
+
tags:
243
+
- subscriptions
244
+
requestBody:
245
+
content:
246
+
application/json:
247
+
schema:
248
+
type: object
249
+
properties:
250
+
nonce:
251
+
type: string
252
+
description: The one time use token issued by Braintree for the new payment method
253
+
examples:
254
+
With a valid token:
255
+
value:
256
+
nonce: "fake-valid-nonce"
257
+
With a bad token:
258
+
value:
259
+
nonce: "fake-processor-declined-visa-nonce"
260
+
responses:
261
+
'200':
262
+
description: "Successfully updated payment method for subcription"
263
+
content: {}
264
+
'400':
265
+
description: "The supplied nonce for the payment method is invalid"
266
+
content:
267
+
application/json:
268
+
schema:
269
+
type: object
270
+
properties:
271
+
errors:
272
+
description: "List of error descriptions"
273
+
type: array
274
+
items:
275
+
type: string
276
+
example: "Payment method failed to be verified."
277
+
'404':
278
+
description: "The subscription cannot be found"
279
+
'401':
280
+
description: "The request is missing the authorization key"
281
+
content: {}
282
+
'403':
283
+
description: "The request has a malformed or expired authorization key"
284
+
content: {}
285
+
'500':
286
+
description: "An unknown exception has occured; consumer should contact the subscription team to resolve this."
287
+
components:
288
+
schemas:
289
+
Subscription:
290
+
type: object
291
+
properties:
292
+
cardNumber:
293
+
type: string
294
+
example: "1123"
295
+
description: The last 4 digits of credit card used for the recurring payment
296
+
expirationDate:
297
+
type: string
298
+
example: "07/2021"
299
+
description: The expiration month and year of the card used for the curring payment
300
+
renewalDate:
301
+
type: string
302
+
format: date
303
+
description: The next date for which the subscription will be renewed/charged its monthly fee.
304
+
billingPeriodStartDate:
305
+
type: string
306
+
format: date | "Invalid date"
307
+
example: "2021-05-08"
308
+
description: The charge date in the current subscription billing cycle. If the subscription has never been charged (i.e. within its trial period), then the value will be "Invalid date".
309
+
planName:
310
+
type: string
311
+
description: The name of the subscription plan
312
+
enum:
313
+
- Price Match
314
+
- Coffee
315
+
- Hot Drinks
316
+
planPrice:
317
+
type: string
318
+
format: money
319
+
description: The fee charged on the recurring schedule
320
+
example: "0.99"
321
+
createdAt:
322
+
type: string
323
+
format: date-time
324
+
example: "2021-05-08T20:29:03.919Z"
325
+
subscriptionId:
326
+
type: string
327
+
format: uuid
328
+
description: The id for the subscription
329
+
state:
330
+
oneOf:
331
+
- type: object
332
+
description: "An active subscription"
333
+
properties:
334
+
status:
335
+
type: "string"
336
+
example: "active"
337
+
- type: object
338
+
description: "A past due subscription. The subscription failed to be renewed but is still within the 3 day grace period (inclusive of the renewal date) where there will be daily attempts to charge for the subscription fee."
339
+
properties:
340
+
status:
341
+
type: "string"
342
+
example: "pastdue"
343
+
- type: object
344
+
description: "A canceled subscription. The subscription has gone past the last paid through date."
345
+
properties:
346
+
status:
347
+
type: "string"
348
+
example: "canceled"
349
+
cancellationReason:
350
+
description: "MEMBER_INITIATED: if the member initiated the cancellation voluntarily. PAYMENT_FAILURE: if all attempts at charging the subscription for renewal failed and the subscription is automatically canceled as a result."
351
+
type: string
352
+
enum:
353
+
- "MEMBER_INITIATED"
354
+
- "PAYMENT_FAILURE"
355
+
endDate:
356
+
type: string
357
+
format: date
358
+
description: "The last date for which the subscription has been paid through."
359
+
example: "2021-08-01"
360
+
- type: object
361
+
description: "A subscription that has been canceled, but still within its paid through period. Only subscriptions canceled by the subscriber voluntarily will be in residual states."
362
+
properties:
363
+
status:
364
+
type: "string"
365
+
example: "residual"
366
+
cancellationReason:
367
+
type: string
368
+
enum:
369
+
- "MEMBER_INITIATED"
370
+
endDate:
371
+
type: string
372
+
format: date
373
+
description: "The last date for which the subscription has been paid through; the member will continue to receive the paid for services until, and including, this date."
374
+
example: "2021-08-01"
375
+
LoyaltyProgram:
376
+
description: "The loyalty program the subscription is under"
377
+
type: string
378
+
enum:
379
+
- bpme-us
380
+
- bpme-uk
381
+
- ampm
382
+
securitySchemes:
383
+
UserJWT:
384
+
description: "The end user JWT issued by Salesforce for the user session."
0 commit comments