TypeScript types, Zod schemas, and Axios client for PayPal Cart API v1
npm install @paypal/agentic-commerce-specTypeScript types, Zod schemas, and Axios client for PayPal Cart API v1, generated from OpenAPI specification.
This package provides comprehensive TypeScript support for PayPal Cart API v1, enabling AI-powered agentic commerce integrations:
- TypeScript Types: Complete type definitions for all API operations
- Zod Schemas: Runtime validation for request/response data
- Axios Client: HTTP client with full type safety
- SDK Functions: Typed functions for each API endpoint
Generated automatically from the official OpenAPI specification using @hey-api/openapi-ts.
``bash`
npm install @paypal/agentic-commerce-spec
`typescript
import {
PayPalCart,
createCart,
getCart,
updateCart,
payPalCartSchema,
client,
} from "@paypal/agentic-commerce-spec";
// Create a new cart
const cartData = {
items: [
{
item_id: "ITEM123",
variant_id: "VAR456",
quantity: 2,
unit_price: "29.99",
},
],
totals: {
total: "59.98",
currency_code: "USD",
},
};
const newCart = await createCart({
body: cartData,
});
console.log("Cart created:", newCart.data);
`
`typescript
import { payPalCartSchema, createCart } from "@paypal/agentic-commerce-spec";
// Validate incoming data
const validatedCart = payPalCartSchema.parse(unknownCartData);
// Validate request before API call
const result = await createCart({ body: validatedCart });
`
`typescript
import { client } from "@paypal/agentic-commerce-spec";
// Configure the HTTP client
client.setConfig({
baseURL: "https://your-api-server.com/api/paypal/v1",
headers: {
Authorization: "Bearer your-jwt-token",
},
});
`
`typescript
import { createCart } from "@paypal/agentic-commerce-spec";
try {
const cart = await createCart({ body: cartData });
if (cart.data?.validation_issues?.length) {
console.log("Validation issues:", cart.data.validation_issues);
}
} catch (error) {
console.error("API Error:", error);
}
`
- createCart(options) - Create a new cart
- getCart(options) - Retrieve cart by ID
- updateCart(options) - Update existing cart
- checkoutCart(options) - Complete cart checkout
Key types exported from the package:
`typescript
// Core cart type
type PayPalCart = {
id?: string;
status?: "CREATED" | "INCOMPLETE" | "READY" | "COMPLETED";
items: CartItem[];
totals?: CartTotals;
shipping_address?: Address;
billing_address?: Address;
payment_method?: PaymentMethod;
validation_issues?: ValidationIssue[];
// ... additional fields
};
// API request/response types
type CreateCartRequest = {
/ ... /
};
type CreateCartResponse = {
/ ... /
};
type UpdateCartRequest = {
/ ... /
};
type CheckoutRequest = {
/ ... /
};
`
`typescript
import {
// Types
PayPalCart,
CartItem,
ValidationIssue,
// SDK Functions
createCart,
getCart,
updateCart,
// Zod Schemas
payPalCartSchema,
// Client
client,
} from "@paypal/agentic-commerce-spec";
// Configure authentication
client.setConfig({
baseURL: "https://your-api-server.com/api/paypal/v1",
headers: {
Authorization: "Bearer YOUR_PAYPAL_JWT_TOKEN",
},
});
// Validate and create cart
const validatedCart = payPalCartSchema.parse(incomingData);
const result = await createCart({ body: validatedCart });
`
The API requires JWT authentication. Set up your client with proper headers:
`typescript
import { client } from "@paypal/agentic-commerce-spec";
client.setConfig({
headers: {
Authorization: "Bearer YOUR_PAYPAL_JWT_TOKEN",
},
});
`
Understanding cart statuses is crucial for proper integration:
- CREATED - Cart successfully created and ready for payment
- INCOMPLETE - Cart has validation issues that need resolution
- READY - Previously incomplete cart is now ready
- COMPLETED - Order finished, payment captured
`typescript
const cart = await createCart({ body: cartData });
switch (cart.data?.status) {
case "CREATED":
// Proceed to payment
break;
case "INCOMPLETE":
// Handle validation issues
console.log("Issues:", cart.data.validation_issues);
break;
case "READY":
// Cart is ready for checkout
break;
case "COMPLETED":
// Order complete
break;
}
`
When a cart has validation issues, they're returned in the validation_issues array:
`typescript`
type ValidationIssue = {
code: string;
type: string;
message: string;
user_message?: string;
item_id?: string;
field?: string;
context?: Record
};
Handle validation issues appropriately:
`typescript${issue.type}: ${issue.message}
if (cart.data?.validation_issues?.length) {
cart.data.validation_issues.forEach((issue) => {
console.log();Affects item: ${issue.item_id}
if (issue.item_id) {
console.log();`
}
});
}
This package uses pre-generated code committed to the repository. To regenerate:
`bashFrom the package directory
npm run generate
Architecture
`
Customer ↔ AI Agent ↔ PayPal Commerce Platform ↔ Your Merchant API
``This package facilitates the "Your Merchant API" integration with PayPal's commerce platform.
Apache-2.0
For issues and questions: