1openapi: 3.0.3
2info:
3 title: WHMCS API
4 description: WHMCS API
5 version: 2.0.0
6servers:
7 - url: '/api/v2'
8
9paths:
10 /status:
11 get:
12 description: Retrieve the API system status.
13 responses:
14 200:
15 description: Success
16 content:
17 application/json:
18 schema:
19 required:
20 - data
21 properties:
22 data:
23 type: object
24 required:
25 - server_time
26 - timezone
27 - currencies
28 properties:
29 server_time:
30 type: string
31 example: 2022-02-06T21:04:45+00:00
32 format: date-time
33 timezone:
34 type: string
35 example: UTC
36 currencies:
37 type: array
38 items:
39 $ref: "#/components/schemas/Currency"
40
41 default:
42 $ref: '#/components/responses/GeneralError'
43
44 /keepalive:
45 post:
46 description: Refresh the session's state.
47 responses:
48 200:
49 description: Success
50 default:
51 $ref: '#/components/responses/GeneralError'
52
53 /currencies:
54 get:
55 description: Retrieve all supported currencies.
56 responses:
57 200:
58 description: Success
59 content:
60 application/json:
61 schema:
62 required:
63 - data
64 properties:
65 data:
66 type: array
67 items:
68 $ref: '#/components/schemas/Currency'
69
70 default:
71 $ref: '#/components/responses/GeneralError'
72
73 /cycles:
74 get:
75 description: List recurring cycles.
76 responses:
77 200:
78 description: Success
79 content:
80 application/json:
81 schema:
82 required:
83 - data
84 properties:
85 data:
86 type: array
87 items:
88 $ref: '#/components/schemas/RecurringCycle'
89
90 default:
91 $ref: '#/components/responses/GeneralError'
92
93 /store/products/groups:
94 get:
95 description: Retrieve all product groups.
96 responses:
97 200:
98 description: A list of all product groups.
99 content:
100 application/json:
101 schema:
102 required:
103 - data
104 properties:
105 data:
106 type: array
107 items:
108 $ref: '#/components/schemas/ProductGroup'
109
110 default:
111 $ref: '#/components/responses/GeneralError'
112
113 /store/products/groups/{group_id}:
114 get:
115 description: Retrieve a specific product group's data.
116 parameters:
117 - $ref: "#/components/parameters/group_id"
118 responses:
119 200:
120 description: A list of all product groups.
121 content:
122 application/json:
123 schema:
124 required:
125 - data
126 properties:
127 data:
128 type: object
129 allOf:
130 - $ref: '#/components/schemas/ProductGroup'
131 - required:
132 - products
133
134 404:
135 $ref: '#/components/responses/NotFound'
136
137 default:
138 $ref: '#/components/responses/GeneralError'
139
140 /store/products/{product_id}/addons:
141 get:
142 description: Retrieve addons for a specific product.
143 parameters:
144 - $ref: "#/components/parameters/product_id"
145 responses:
146 200:
147 description: A list of all product addons.
148 content:
149 application/json:
150 schema:
151 required:
152 - data
153 properties:
154 data:
155 type: array
156 items:
157 $ref: '#/components/schemas/Addon'
158
159 404:
160 $ref: '#/components/responses/NotFound'
161
162 default:
163 $ref: '#/components/responses/GeneralError'
164
165 /cart:
166 post:
167 description: Create a new cart.
168 responses:
169 200:
170 description: Newly-created cart data.
171 content:
172 application/json:
173 schema:
174 required:
175 - data
176 properties:
177 data:
178 $ref: '#/components/schemas/Cart'
179 default:
180 $ref: '#/components/responses/GeneralError'
181
182 get:
183 description: List all carts associated with logged-in user.
184 responses:
185 200:
186 description: All of the carts for the logged-in user.
187 content:
188 application/json:
189 schema:
190 required:
191 - data
192 properties:
193 data:
194 type: array
195 items:
196 $ref: '#/components/schemas/Cart'
197
198 default:
199 $ref: '#/components/responses/GeneralError'
200
201 /cart/{cart_id}/totals:
202 get:
203 description: Get cart totals.
204 parameters:
205 - $ref: "#/components/parameters/cart_id"
206 responses:
207 200:
208 description: The cart total.
209 content:
210 application/json:
211 schema:
212 required:
213 - data
214 properties:
215 data:
216 $ref: '#/components/schemas/CartTotal'
217 404:
218 $ref: '#/components/responses/NotFound'
219
220 default:
221 $ref: '#/components/responses/GeneralError'
222
223 /cart/{cart_id}/items/{item_id}:
224 delete:
225 description: Delete an item from the cart.
226 parameters:
227 - $ref: "#/components/parameters/cart_id"
228 - $ref: "#/components/parameters/cart_item_id"
229 responses:
230 200:
231 description: Success
232 content:
233 application/json:
234 schema:
235 required:
236 - data
237 properties:
238 data:
239 $ref: '#/components/schemas/CartTotal'
240 404:
241 $ref: '#/components/responses/NotFound'
242 default:
243 $ref: '#/components/responses/GeneralError'
244
245 /cart/{cart_id}/items:
246 get:
247 description: Get cart items.
248 parameters:
249 - $ref: "#/components/parameters/cart_id"
250 responses:
251 200:
252 description: Success
253 content:
254 application/json:
255 schema:
256 required:
257 - data
258 properties:
259 data:
260 type: array
261 items:
262 anyOf:
263 - $ref: '#/components/schemas/CartItemTypeProduct'
264 404:
265 $ref: '#/components/responses/NotFound'
266 default:
267 $ref: '#/components/responses/GeneralError'
268
269 post:
270 description: Add one or more items to the cart.
271 parameters:
272 - $ref: "#/components/parameters/cart_id"
273 requestBody:
274 required: true
275 content:
276 application/json:
277 schema:
278 properties:
279 items:
280 type: array
281 items:
282 anyOf:
283 - $ref: '#/components/schemas/CartItemTypeProduct'
284 responses:
285 200:
286 description: Success
287 content:
288 application/json:
289 schema:
290 required:
291 - data
292 properties:
293 data:
294 $ref: '#/components/schemas/CartTotal'
295 404:
296 $ref: '#/components/responses/NotFound'
297 default:
298 $ref: '#/components/responses/GeneralError'
299
300 delete:
301 description: Remove all items from cart.
302 parameters:
303 - $ref: "#/components/parameters/cart_id"
304 responses:
305 200:
306 description: Success
307 content:
308 application/json:
309 schema:
310 required:
311 - data
312 properties:
313 data:
314 $ref: '#/components/schemas/CartTotal'
315 404:
316 $ref: '#/components/responses/NotFound'
317 default:
318 $ref: '#/components/responses/GeneralError'
319
320 /cart/{cart_id}/promotion:
321 get:
322 description: Get the currently-applied promotion code.
323 parameters:
324 - $ref: "#/components/parameters/cart_id"
325 responses:
326 200:
327 description: Success
328 content:
329 application/json:
330 schema:
331 required:
332 - data
333 properties:
334 data:
335 $ref: '#/components/schemas/Promotion'
336 404:
337 $ref: '#/components/responses/NotFound'
338 default:
339 $ref: '#/components/responses/GeneralError'
340 post:
341 description: Apply a promotion code to the cart.
342 parameters:
343 - $ref: "#/components/parameters/cart_id"
344 requestBody:
345 required: true
346 content:
347 application/json:
348 schema:
349 $ref: '#/components/schemas/Promotion'
350 responses:
351 200:
352 description: Success
353 content:
354 application/json:
355 schema:
356 required:
357 - data
358 properties:
359 data:
360 $ref: '#/components/schemas/CartTotal'
361 422:
362 description: Invalid Promotion Code
363 content:
364 application/json:
365 schema:
366 $ref: '#/components/schemas/GeneralError'
367 default:
368 $ref: '#/components/responses/GeneralError'
369 delete:
370 description: Remove the promotion code from the cart.
371 parameters:
372 - $ref: "#/components/parameters/cart_id"
373 responses:
374 200:
375 description: Success
376 content:
377 application/json:
378 schema:
379 required:
380 - data
381 properties:
382 data:
383 $ref: '#/components/schemas/CartTotal'
384 404:
385 $ref: '#/components/responses/NotFound'
386 default:
387 $ref: '#/components/responses/GeneralError'
388
389 /cart/{cart_id}/checkout:
390 post:
391 description: Begin the checkout process.
392 parameters:
393 - $ref: "#/components/parameters/cart_id"
394 responses:
395 200:
396 description: Success
397 content:
398 application/json:
399 schema:
400 required:
401 - data
402 properties:
403 data:
404 type: object
405 required:
406 - url
407 properties:
408 url:
409 type: string
410 example: https://example.com/
411 404:
412 $ref: '#/components/responses/NotFound'
413 default:
414 $ref: '#/components/responses/GeneralError'
415
416 /user/session:
417 post:
418 description: Begin a user's session.
419 requestBody:
420 required: true
421 content:
422 application/json:
423 schema:
424 type: object
425 required:
426 - email
427 - password
428 properties:
429 email:
430 allOf:
431 - description: The user's email address.
432 - $ref: '#/components/schemas/Email'
433 password:
434 allOf:
435 - description: The user's password.
436 - $ref: '#/components/schemas/Password'
437
438 responses:
439 200:
440 description: Success
441 content:
442 application/json:
443 schema:
444 required:
445 - data
446 properties:
447 data:
448 $ref: '#/components/schemas/User'
449
450 404:
451 $ref: '#/components/responses/NotFound'
452 412:
453 description: A second authentication factor is required to finish login.
454 content:
455 application/json:
456 schema:
457 $ref: '#/components/schemas/SecondFactorChallenge'
458 default:
459 $ref: '#/components/responses/GeneralError'
460
461 delete:
462 description: Log out of the user session.
463 responses:
464 200:
465 description: Success
466 404:
467 $ref: '#/components/responses/NotFound'
468 default:
469 $ref: '#/components/responses/GeneralError'
470
471 /user/session/verify:
472 post:
473 description: Submit a user's two-factor challenge response.
474 requestBody:
475 required: true
476 content:
477 application/json:
478 schema:
479 type: object
480 example: {"key":"677440"}
481 required:
482 - fields
483 properties:
484 fields:
485 type: object
486
487 responses:
488 200:
489 description: Success
490 content:
491 application/json:
492 schema:
493 required:
494 - data
495 properties:
496 data:
497 $ref: '#/components/schemas/User'
498
499 412:
500 description: The provided second factor is invalid.
501 content:
502 application/json:
503 schema:
504 $ref: '#/components/schemas/GeneralError'
505 default:
506 $ref: '#/components/responses/GeneralError'
507
508 /user/clients:
509 get:
510 description: List the user's associated clients.
511 responses:
512 200:
513 description: Success
514 content:
515 application/json:
516 schema:
517 required:
518 - data
519 properties:
520 data:
521 type: array
522 items:
523 $ref: '#/components/schemas/Client'
524 default:
525 $ref: '#/components/responses/GeneralError'
526
527 /user/session/client/{client_id}:
528 put:
529 description: Select an active client for the logged-in user.
530 parameters:
531 - $ref: "#/components/parameters/client_id"
532 responses:
533 200:
534 description: Success
535 default:
536 $ref: '#/components/responses/GeneralError'
537
538components:
539 schemas:
540 GeneralError:
541 type: object
542 properties:
543 message:
544 type: string
545
546 CartItemId:
547 description: Unique cart item ID. Automatically generated when an item is added to cart.
548 type: string
549 minLength: 8
550 maxLength: 16
551
552 CartItemTypeProduct:
553 type: object
554 properties:
555 item_id:
556 $ref: "#/components/schemas/CartItemId"
557 type:
558 type: string
559 enum: [product]
560 example: product
561 product_id:
562 type: integer
563 format: int64
564 example: 123
565 billing_cycle:
566 $ref: '#/components/schemas/BillingCycle'
567 domain:
568 type: string
569 nullable: true
570 example: example.com
571 addons:
572 type: array
573 items:
574 $ref: '#/components/schemas/CartItemTypeProductAddon'
575 required:
576 - type
577 - product_id
578 - billing_cycle
579
580 CartItemTypeProductAddon:
581 type: object
582 properties:
583 item_id:
584 $ref: "#/components/schemas/CartItemId"
585 addon_id:
586 type: integer
587 format: int64
588 example: 456
589 quantity:
590 type: integer
591 format: int32
592 example: 5
593 required:
594 - addon_id
595
596 CartItemTypeServiceAddon:
597 type: object
598 properties:
599 item_id:
600 $ref: "#/components/schemas/CartItemId"
601 type:
602 type: string
603 enum: [addon]
604 example: addon
605 addon_id:
606 type: integer
607 format: int64
608 example: 456
609 service_id:
610 type: integer
611 format: int64
612 example: 123
613 billing_cycle:
614 $ref: '#/components/schemas/BillingCycle'
615 quantity:
616 type: integer
617 format: int32
618 nullable: true
619 required:
620 - type
621 - addon_id
622
623 ProductGroup:
624 type: object
625 required:
626 - id
627 - name
628 properties:
629 id:
630 type: integer
631 format: int64
632 example: 1
633 name:
634 type: string
635 example: Web hosting
636 products:
637 type: array
638 items:
639 $ref: '#/components/schemas/Product'
640
641 Product:
642 type: object
643 required:
644 - id
645 - name
646 - pricing
647 properties:
648 id:
649 type: integer
650 format: int64
651 example: 123
652 name:
653 type: string
654 minLength: 3
655 example: Shared web hosting
656 description:
657 type: string
658 pricing:
659 $ref: '#/components/schemas/Pricing'
660
661 Addon:
662 type: object
663 required:
664 - id
665 - name
666 - pricing
667 properties:
668 id:
669 type: integer
670 format: int64
671 example: 456
672 name:
673 type: string
674 minLength: 3
675 example: Extra disk space
676 description:
677 type: string
678 pricing:
679 $ref: '#/components/schemas/Pricing'
680
681 Pricing:
682 type: object
683 required:
684 - is_free
685 properties:
686 is_free:
687 type: boolean
688 onetime:
689 $ref: '#/components/schemas/OneTimePrice'
690 recurring:
691 $ref: '#/components/schemas/RecurringPricing'
692
693 Amount:
694 type: object
695 properties:
696 value:
697 type: string
698 example: "19.99"
699 code:
700 $ref: "#/components/schemas/CurrencyCode"
701
702 Currency:
703 type: object
704 properties:
705 code:
706 $ref: "#/components/schemas/CurrencyCode"
707 prefix:
708 type: string
709 description: Optional currency prefix
710 example: "$"
711 suffix:
712 type: string
713 description: Optional currency prefix
714 example: USD
715 default:
716 type: boolean
717 description: This is true if the currency is currently the system default.
718
719 CurrencyCode:
720 type: string
721 pattern: "^[A-Z]{3}$"
722 example: USD
723
724 Email:
725 type: string
726 minLength: 6
727 maxLength: 255
728 example: me@example.com
729
730 Password:
731 type: string
732 minLength: 4
733 maxLength: 64
734 example: NeedNewPassword!!!
735
736 Name:
737 type: string
738 minLength: 2
739 maxLength: 64
740 example: Davis
741
742 User:
743 type: object
744 description: Logged-in user data.
745 required:
746 - email
747 - firstname
748 - lastname
749 - clients
750 properties:
751 email:
752 $ref: '#/components/schemas/Email'
753 firstname:
754 $ref: '#/components/schemas/Name'
755 lastname:
756 $ref: '#/components/schemas/Name'
757 clients:
758 type: array
759 items:
760 $ref: '#/components/schemas/Client'
761
762 Client:
763 type: object
764 required:
765 - id
766 properties:
767 id:
768 type: string
769 minLength: 36
770 maxLength: 36
771 example: 11C2M72y-z54n-5721-nnF8-13492be5uHiu
772 company:
773 type: string
774 maxLength: 64
775 selected:
776 type: boolean
777
778 RecurringPricing:
779 type: array
780 items:
781 $ref: '#/components/schemas/RecurringPrice'
782
783 OneTimePrice:
784 type: object
785 properties:
786 setup:
787 $ref: '#/components/schemas/Amount'
788 amount:
789 $ref: '#/components/schemas/Amount'
790
791 RecurringPrice:
792 type: object
793 required:
794 - cycle
795 - amount
796 properties:
797 cycle:
798 $ref: '#/components/schemas/BillingCycle'
799 setup:
800 $ref: '#/components/schemas/Amount'
801 amount:
802 $ref: '#/components/schemas/Amount'
803
804 RecurringCycle:
805 type: object
806 required:
807 - cycle
808 properties:
809 cycle:
810 $ref: '#/components/schemas/BillingCycle'
811 description:
812 type: string
813 example: Monthly
814 months:
815 type: integer
816 format: int32
817 description: The number of months for this cycle.
818 example: 1
819
820 BillingCycle:
821 type: string
822 description: Billing cycle's frequency.
823 example: monthly
824 enum:
825 - onetime
826 - monthly
827 - quarterly
828 - semiannually
829 - annually
830 - biennially
831 - triennially
832
833 CartTotal:
834 type: object
835 properties:
836 recurring:
837 $ref: '#/components/schemas/RecurringPricing'
838 subtotal:
839 $ref: '#/components/schemas/Amount'
840 discount:
841 type: array
842 items:
843 $ref: '#/components/schemas/Discount'
844 tax:
845 type: array
846 items:
847 $ref: '#/components/schemas/Tax'
848 total:
849 $ref: '#/components/schemas/Amount'
850
851 Tax:
852 type: object
853 required:
854 - name
855 - percentage
856 - amount
857 properties:
858 name:
859 type: string
860 percentage:
861 type: number
862 format: float
863 multipleOf: 0.001
864 example: 7.5
865 amount:
866 $ref: '#/components/schemas/Amount'
867
868 Discount:
869 type: object
870 required:
871 - name
872 - amount
873 properties:
874 name:
875 type: string
876 enum: [promo, client_group]
877 amount:
878 $ref: '#/components/schemas/Amount'
879
880 Cart:
881 type: object
882 required:
883 - id
884 properties:
885 id:
886 type: string
887 minLength: 16
888 maxLength: 16
889 example: V8UH6nyaU6Hj8hCh
890
891 Promotion:
892 type: object
893 required:
894 - code
895 properties:
896 code:
897 type: string
898 nullable: true
899 example: PROMOCODE
900
901 TwoFaField:
902 type: object
903 required:
904 - name
905 - type
906 properties:
907 name:
908 type: string
909 minLength: 1
910 maxLength: 64
911 description:
912 type: string
913 maxLength: 64
914 type:
915 enum:
916 - number
917 - text
918
919 SecondFactorChallenge:
920 description: Second factor challenge information.
921 properties:
922 condition:
923 enum:
924 - twofa
925 fields:
926 type: array
927 items:
928 $ref: '#/components/schemas/TwoFaField'
929
930 parameters:
931 cart_item_id:
932 name: item_id
933 in: path
934 description: Cart Item ID
935 required: true
936 schema:
937 type: string
938 minLength: 8
939 maxLength: 8
940
941 group_id:
942 name: group_id
943 in: path
944 description: Product Group ID
945 required: true
946 schema:
947 type: integer
948 format: int64
949
950 product_id:
951 name: product_id
952 in: path
953 description: Product ID
954 required: true
955 schema:
956 type: integer
957 format: int64
958
959 cart_id:
960 name: cart_id
961 in: path
962 description: Cart ID
963 required: true
964 schema:
965 type: string
966 minLength: 16
967 maxLength: 16
968
969 client_id:
970 name: client_id
971 in: path
972 description: Client ID
973 required: true
974 schema:
975 type: string
976 minLength: 36
977 maxLength: 36
978 example: 11C2M72y-z54n-5721-nnF8-13492be5uHiu
979
980 responses:
981 NotFound:
982 description: Entity Not Found
983 content:
984 application/json:
985 schema:
986 $ref: '#/components/schemas/GeneralError'
987
988 GeneralError:
989 description: General Error
990 content:
991 application/json:
992 schema:
993 $ref: '#/components/schemas/GeneralError'
994