Skip to content

Commit e5b3620

Browse files
armando-rodriguez-ckoarmando-rodriguez-cko
authored
feat(inventory): add Inventory endpoint family (#672)
Implements the new agentic:inventory OAuth-scoped endpoints: stock adjustments, atomic multi-variant reservations (create/get/commit/release), stock levels (get/set), and beta product knowledge (get/set/delete). Error responses (404/409/422) surface through the SDK's existing generic CheckoutApiException map, documented in Javadoc rather than a dedicated per-domain error class, consistent with the rest of the SDK.
1 parent 3d662ae commit e5b3620

26 files changed

Lines changed: 2456 additions & 0 deletions

‎src/main/java/com/checkout/CheckoutApi.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
import com.checkout.identities.addressdocumentverification.AddressDocumentVerificationClient;
2121
import com.checkout.identities.amlscreening.AmlScreeningClient;
2222
import com.checkout.instruments.InstrumentsClient;
23+
import com.checkout.inventory.InventoryClient;
2324
import com.checkout.issuing.IssuingClient;
2425
import com.checkout.metadata.MetadataClient;
2526
import com.checkout.networktokens.NetworkTokensClient;
@@ -59,6 +60,8 @@ public interface CheckoutApi extends CheckoutApmApi {
5960

6061
ForexClient forexClient();
6162

63+
InventoryClient inventoryClient();
64+
6265
PaymentLinksClient paymentLinksClient();
6366

6467
PaymentMethodsClient paymentMethodsClient();

‎src/main/java/com/checkout/CheckoutApiImpl.java‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,8 @@
4040
import com.checkout.identities.amlscreening.AmlScreeningClientImpl;
4141
import com.checkout.instruments.InstrumentsClient;
4242
import com.checkout.instruments.InstrumentsClientImpl;
43+
import com.checkout.inventory.InventoryClient;
44+
import com.checkout.inventory.InventoryClientImpl;
4345
import com.checkout.issuing.IssuingClient;
4446
import com.checkout.issuing.IssuingClientImpl;
4547
import com.checkout.metadata.MetadataClient;
@@ -87,6 +89,7 @@ public class CheckoutApiImpl extends AbstractCheckoutApmApi implements CheckoutA
8789
private final AccountsClient accountsClient;
8890
private final SessionsClient sessionsClient;
8991
private final ForexClient forexClient;
92+
private final InventoryClient inventoryClient;
9093
private final PaymentLinksClient paymentLinksClient;
9194
private final PaymentMethodsClient paymentMethodsClient;
9295
private final HostedPaymentsClient hostedPaymentsClient;
@@ -125,6 +128,7 @@ public CheckoutApiImpl(final CheckoutConfiguration configuration) {
125128
this.workflowsClient = new WorkflowsClientImpl(this.apiClient, configuration);
126129
this.sessionsClient = new SessionsClientImpl(this.apiClient, configuration);
127130
this.forexClient = new ForexClientImpl(this.apiClient, configuration);
131+
this.inventoryClient = new InventoryClientImpl(this.apiClient, configuration);
128132
this.paymentLinksClient = new PaymentLinksClientImpl(this.apiClient, configuration);
129133
this.paymentMethodsClient = new PaymentMethodsClientImpl(this.apiClient, configuration);
130134
this.hostedPaymentsClient = new HostedPaymentsClientImpl(this.apiClient, configuration);
@@ -207,6 +211,11 @@ public ForexClient forexClient() {
207211
return forexClient;
208212
}
209213

214+
@Override
215+
public InventoryClient inventoryClient() {
216+
return inventoryClient;
217+
}
218+
210219
@Override
211220
public PaymentLinksClient paymentLinksClient() {
212221
return paymentLinksClient;

‎src/main/java/com/checkout/inventory/InventoryClient.java‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
package com.checkout.inventory;
2+
3+
import com.checkout.EmptyResponse;
4+
import com.checkout.inventory.request.InventoryAdjustmentRequest;
5+
import com.checkout.inventory.request.InventoryLevelsQueryFilter;
6+
import com.checkout.inventory.request.InventoryReservationRequest;
7+
import com.checkout.inventory.request.InventorySetLevelsRequest;
8+
import com.checkout.inventory.request.InventorySetProductRequest;
9+
import com.checkout.inventory.response.InventoryLevels;
10+
import com.checkout.inventory.response.InventoryProductKnowledge;
11+
import com.checkout.inventory.response.InventoryReservation;
12+
13+
import java.util.concurrent.CompletableFuture;
14+
15+
/**
16+
* The Inventory client: stock levels, atomic multi-variant reservations, stock adjustments, and
17+
* per-variant product knowledge for AI agents. Every operation on this client requires the
18+
* {@code agentic:inventory} OAuth scope; it does not accept a secret or public API key.
19+
*
20+
* <p>Error responses ({@code 404}, {@code 409}, {@code 422}) are surfaced the same way as every
21+
* other domain in this SDK: as a {@link com.checkout.CheckoutApiException} carrying the raw
22+
* {@code Map<String, Object>} error body, not a typed class (this SDK has no domain that
23+
* deserializes error bodies into a dedicated type). For the inventory endpoints, that map
24+
* contains: {@code request_id} (String, for support and correlation), {@code error_type}
25+
* (String, a high-level classification), {@code error_codes} (array of String, in
26+
* {@code [subject]_[error]} form), and, present only on an {@code insufficient_stock} conflict,
27+
* {@code variant_id} (String, the first failing variant) and {@code available} (Integer, its
28+
* current sellable availability).</p>
29+
*/
30+
public interface InventoryClient {
31+
32+
/**
33+
* Applies a relative adjustment to a variant's on-hand stock.
34+
*
35+
* @param request the adjustment to apply
36+
* @return the variant's resulting stock levels
37+
*/
38+
CompletableFuture<InventoryLevels> adjustInventory(InventoryAdjustmentRequest request);
39+
40+
/**
41+
* Applies a relative adjustment to a variant's on-hand stock.
42+
*
43+
* @param request the adjustment to apply
44+
* @param idempotencyKey an optional idempotency key sent as {@code Cko-Idempotency-Key}
45+
* @return the variant's resulting stock levels
46+
*/
47+
CompletableFuture<InventoryLevels> adjustInventory(InventoryAdjustmentRequest request, String idempotencyKey);
48+
49+
/**
50+
* Retrieves the current stock levels for a variant.
51+
*
52+
* @param variantId the identifier of the variant
53+
* @return the variant's current stock levels
54+
*/
55+
CompletableFuture<InventoryLevels> getInventoryLevels(String variantId);
56+
57+
/**
58+
* Retrieves the current stock levels for a variant.
59+
*
60+
* @param variantId the identifier of the variant
61+
* @param filter optional query parameters, for example {@code expand=product}
62+
* @return the variant's current stock levels
63+
*/
64+
CompletableFuture<InventoryLevels> getInventoryLevels(String variantId, InventoryLevelsQueryFilter filter);
65+
66+
/**
67+
* Sets absolute stock levels for a variant. Creates the inventory item if it does not exist.
68+
*
69+
* @param variantId the identifier of the variant
70+
* @param request the absolute stock levels to set
71+
* @return the variant's resulting stock levels
72+
*/
73+
CompletableFuture<InventoryLevels> setInventoryLevels(String variantId, InventorySetLevelsRequest request);
74+
75+
/**
76+
* Creates an atomic multi-variant stock hold.
77+
*
78+
* @param request the reservation to create
79+
* @return the created reservation
80+
*/
81+
CompletableFuture<InventoryReservation> createInventoryReservation(InventoryReservationRequest request);
82+
83+
/**
84+
* Creates an atomic multi-variant stock hold.
85+
*
86+
* @param request the reservation to create
87+
* @param idempotencyKey an optional idempotency key sent as {@code Cko-Idempotency-Key}
88+
* @return the created reservation
89+
*/
90+
CompletableFuture<InventoryReservation> createInventoryReservation(InventoryReservationRequest request, String idempotencyKey);
91+
92+
/**
93+
* Retrieves a reservation.
94+
*
95+
* @param reservationId the identifier of the reservation
96+
* @return the reservation
97+
*/
98+
CompletableFuture<InventoryReservation> getInventoryReservation(String reservationId);
99+
100+
/**
101+
* Commits a held reservation, converting the hold into a permanent stock deduction.
102+
*
103+
* @param reservationId the identifier of the reservation
104+
* @return the committed reservation
105+
*/
106+
CompletableFuture<InventoryReservation> commitInventoryReservation(String reservationId);
107+
108+
/**
109+
* Releases a held reservation, returning the held quantities to available stock.
110+
*
111+
* @param reservationId the identifier of the reservation
112+
* @return the released reservation
113+
*/
114+
CompletableFuture<InventoryReservation> releaseInventoryReservation(String reservationId);
115+
116+
/**
117+
* Beta. Retrieves the product knowledge for a variant.
118+
*
119+
* @param variantId the identifier of the variant
120+
* @return the variant's product knowledge
121+
*/
122+
CompletableFuture<InventoryProductKnowledge> getInventoryProduct(String variantId);
123+
124+
/**
125+
* Beta. Sets (upserts) the product knowledge for a variant.
126+
*
127+
* @param variantId the identifier of the variant
128+
* @param request the product knowledge to set
129+
* @return the resulting product knowledge
130+
*/
131+
CompletableFuture<InventoryProductKnowledge> setInventoryProduct(String variantId, InventorySetProductRequest request);
132+
133+
/**
134+
* Beta. Deletes the product knowledge for a variant.
135+
*
136+
* @param variantId the identifier of the variant
137+
* @return an empty response
138+
*/
139+
CompletableFuture<EmptyResponse> deleteInventoryProduct(String variantId);
140+
141+
// Synchronous methods
142+
143+
InventoryLevels adjustInventorySync(InventoryAdjustmentRequest request);
144+
145+
InventoryLevels adjustInventorySync(InventoryAdjustmentRequest request, String idempotencyKey);
146+
147+
InventoryLevels getInventoryLevelsSync(String variantId);
148+
149+
InventoryLevels getInventoryLevelsSync(String variantId, InventoryLevelsQueryFilter filter);
150+
151+
InventoryLevels setInventoryLevelsSync(String variantId, InventorySetLevelsRequest request);
152+
153+
InventoryReservation createInventoryReservationSync(InventoryReservationRequest request);
154+
155+
InventoryReservation createInventoryReservationSync(InventoryReservationRequest request, String idempotencyKey);
156+
157+
InventoryReservation getInventoryReservationSync(String reservationId);
158+
159+
InventoryReservation commitInventoryReservationSync(String reservationId);
160+
161+
InventoryReservation releaseInventoryReservationSync(String reservationId);
162+
163+
InventoryProductKnowledge getInventoryProductSync(String variantId);
164+
165+
InventoryProductKnowledge setInventoryProductSync(String variantId, InventorySetProductRequest request);
166+
167+
EmptyResponse deleteInventoryProductSync(String variantId);
168+
169+
}

0 commit comments

Comments
 (0)