Getting Started with Nue APIs
29 min
welcome to nue's comprehensive api platform! our apis provide powerful capabilities for managing business processes, from metadata and object management to complete self service workflows and third party integrations this guide will help you get up and running quickly overview nue offers several specialized apis designed to work together seamlessly ๐ metadata api manage business objects, fields, layouts, filters, and value sets ๐ฐ system administration api manage nue system configuration including system settings, the import and export of products and pricing, orders and subscriptions, and other transactions ๐งพ billing and collections api process billing, invoices, credit memos, payments and other financial transactions ๐ lifecycle manager api power customer self service portals and experiences ๐ stripe integration api seamlessly sync data between nue and stripe each api comes with detailed guides covering specific use cases and implementation patterns authentication & api keys getting your api key to access nue apis, you'll need an api key contact your nue administrator or account manager to obtain your key each environment requires a separate api key for security for detailed information on nue api keys, please refer to api keys docid\ ayzvok5akjgnyyrdrunwk api key security best practices never expose api keys in client side code or public repositories store keys securely using environment variables or secure configuration management rotate keys regularly as part of your security practices use different keys for different environments (development, staging, production) authentication method all nue apis use api key authentication via the nue api key header curl h "nue api key your api key here" \\ h "content type application/json" \\ https //api nue io/metadata/objects environments nue provides multiple environments to support your development lifecycle environment base url purpose use case production https //api nue io live production data customer facing applications sandbox https //api sandbox nue io safe testing environment development and testing environment selection choose your environment based on your current development phase development use sandbox for building and testing features staging use sandbox for pre production validation production use production for live customer data making your first request start with a simple authentication test curl h "nue api key your api key here" \\ https //api nue io/metadata/objects a successful response indicates your api key is valid and you're ready to proceed response format & error handling common http status codes code meaning action 200 success request completed successfully 400 bad request check request format and required fields 401 unauthorized verify your api key is correct and active 403 forbidden check your permissions for this operation 404 not found verify the resource exists and the url is correct 409 conflict resource already exists or constraint violation 429 rate limited reduce request frequency 500 server error contact support if issue persists rate limits & performance rate limiting standard rate limits apply to all endpoints limits vary by endpoint and subscription level rate limit headers are included in responses contact support for rate limit increases best practices implement exponential backoff for retries cache responses when appropriate to reduce api calls use pagination for large data sets (see getting started with nue apis /#pagination section below) batch operations when possible monitor rate limit headers to avoid hitting limits async operations some operations (like bulk data imports) are asynchronous returns a job id immediately poll job status endpoints for completion retrieve results when job completes \# set api key as environment variable export nue api key="your api key here" curl h "nue api key $nue api key" \\ h "content type application/json" \\ https //api nue io/metadata/objects pagination nue apis provide comprehensive pagination support for endpoints that return large datasets pagination follows industry standard patterns with consistent parameter names and response structures across all endpoints pagination parameters all paginated endpoints support these query parameters parameter type default maximum description page integer 1 n/a page number (1 based indexing) limit integer 100 500 number of records per page parameter examples \# get first page with default limit (100 records) get /customers?page=1 \# get second page with custom limit (50 records) get /customers?page=2\&limit=50 \# maximum records per page get /customers?page=1\&limit=500 pagination response structure all paginated responses include a pagination object with metadata about the current page and total dataset { "status" "success", "data" \[ ], "warnings" \[], "pagination" { "page" 1, // current page number (1 based) "limit" 100, // records per page "total" 1247, // total number of records available "totalpages" 13, // total number of pages "hasnext" true, // whether there is a next page "hasprevious" false // whether there is a previous page } } pagination fields field type description page integer current page number (starts at 1) limit integer number of records requested per page total integer total count of records across all pages totalpages integer total number of pages available hasnext boolean true if more pages exist after current page hasprevious boolean true if pages exist before current page endpoints with pagination support the following endpoints support pagination customers get /customers orders get /orders invoices get /invoices credit memos get /creditmemos assets get /assets subscriptions get /subscriptions contacts get /contacts entitlements get /entitlements transaction hub get /customers/{customerid}/transactionhubdata navigation examples forward navigation \# start with first page get /customers?page=1\&limit=50 \# navigate to next page using pagination metadata get /customers?page=2\&limit=50 large dataset handling \# for large datasets, use smaller page sizes for better performance get /customers?page=1\&limit=25 \# check pagination metadata to understand total scope \# response "totalpages" 40, "total" 1000 best practices start small use smaller page sizes (25 100) for better initial load times monitor total count check total field to understand dataset size use navigation flags rely on hasnext / hasprevious for navigation logic handle empty results when total is 0, data will be an empty array respect limits maximum page size is 500 records per request cache pagination metadata store pagination info to avoid recalculating navigation error handling invalid page parameters { "status" "failure", "errortype" "invalid parameter", "errorcode" "invalid page parameter", "message" "invalid page parameter '0' page must be a positive integer starting from 1" } invalid limit parameters { "status" "failure", "errortype" "invalid parameter", "errorcode" "invalid limit parameter", "message" "invalid limit parameter '600' limit must be between 1 and 500" } performance considerations efficient pagination uses cursor based pagination internally for optimal database performance consistent ordering results are ordered by lastmodifieddate desc for consistent pagination count optimization total counts are calculated efficiently using database aggregation memory management large datasets are streamed rather than loaded entirely into memory data formats & conventions json standards all request and response bodies use json field names use camelcase convention dates follow iso 8601 format ( yyyy mm ddthh\ mm\ ss sssz ) monetary values are decimal numbers getting help api documentation comprehensive reference for all endpoints support portal submit tickets for technical issues ready to build something amazing? start with our guided tutorials for your specific use case!
