Instant Wins API

This guide provides instructions on using the custom API endpoints for accessing and updating instant win results for your Zap Competitions Instant Win Plugin.

Authentication #

All requests to the API must be authenticated using WooCommerce API authentication methods. WooCommerce uses OAuth 1.0a authentication to ensure secure access to the API.

Creating API Keys #

1. Log in to your WordPress admin panel at /wp-admin/.
2. Go to WooCommerce > Settings > Advanced > REST API.
3. Click on “Add key” to create a new set of API keys.
4. Fill in the description, user, and permissions for the API key.
5. Click “Generate API key” to create your consumer key and consumer secret.

Using API Keys #

When making requests to the API, you need to include your consumer key and consumer secret in the request. There are two methods to authenticate:

1. Query string: Append consumer_key and consumer_secret parameters to the URL. Example: https://zapcompetitions.co.uk/wp-json/wc/v1/instant-win-results?consumer_key=ck_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&consumer_secret=cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
2. OAuth 1.0a: Use OAuth 1.0a authentication method with your consumer key and consumer secret. This method is more secure and recommended for production use.

For detailed information on implementing OAuth 1.0a authentication, please refer to the WooCommerce REST API documentation.

Base URL #

The base URL for all API requests is:

https://zapcompetitions.co.uk/wp-json/wc/v1/

Endpoints #

1. Get Instant Win Results

Endpoint: GET /instant-win-results

This endpoint retrieves instant win results with pagination and filtering options.

Parameters: #

• per_page (optional): Number of results per page. Default is 10, maximum is 100.
• page (optional): Page number. Default is 1.
• date_created (optional): Filter by exact date (format: YYYY-MM-DD).
• date_created_from (optional): Filter by start date (format: YYYY-MM-DD).
• date_created_to (optional): Filter by end date (format: YYYY-MM-DD).
• user_id (optional): Filter by user ID.
• user_email (optional): Filter by user email. This will find the user ID associated with the email and then filter by that user ID.
• order_id (optional): Filter by order ID.
• product_id (optional): Filter by product ID.
• prize_type (optional): Filter by prize type. Accepted values are ‘prize’ or ‘credit’.
• paid (optional): Filter by paid status (true for paid, false for unpaid).

Note: Results are always ordered by id in descending order.

Example Requests: #

1. Get all results for a specific date:

GET https://zapcompetitions.co.uk/wp-json/wc/v1/instant-win-results?date_created=2024-08-29&consumer_key=ck_XXXX&consumer_secret=cs_XXXX

2. Get results for a date range with a specific prize type:

GET https://zapcompetitions.co.uk/wp-json/wc/v1/instant-win-results?date_created_from=2024-08-01&date_created_to=2024-08-31&prize_type=prize&consumer_key=ck_XXXX&consumer_secret=cs_XXXX

3. Get results for a specific user email:

GET https://zapcompetitions.co.uk/wp-json/wc/v1/[email protected]&consumer_key=ck_XXXX&consumer_secret=cs_XXXX

4. Get unpaid results:

GET https://zapcompetitions.co.uk/wp-json/wc/v1/instant-win-results?paid=false&consumer_key=ck_XXXX&consumer_secret=cs_XXXX

Response: #

The response will be a JSON array of objects, each representing an instant win result. The response headers will include pagination information:

• X-WP-Total: Total number of items
• X-WP-TotalPages: Total number of pages

Example Response:

[
  {
    "id": 1,
    "product_id": 123,
    "product_title": "Competition Entry",
    "ticket_no": 1001,
    "prize_type": "prize",
    "title": "Cash Prize",
    "prize_value": 100.00,
    "description": "Congratulations! You've won £100!",
    "image_id": 456,
    "image_url": "https://zapcompetitions.co.uk/wp-content/uploads/2024/08/prize-image.jpg",
    "user_name": "John Doe",
    "user_id": 789,
    "user_firstname": "John",
    "user_lastname": "Doe",
    "user_email": "[email protected]",
    "order_id": 1234,
    "paid": true,
    "date_created": "2024-08-29 12:00:00"
  },
  // ... more results ...
]

Update Paid Status #

Endpoint: POST /update-paid-status/{id}

This endpoint updates the paid status of a specific instant win result to paid (1).

Parameters:

• id (required): The ID of the instant win result to update.

Example Request:

POST https://zapcompetitions.co.uk/wp-json/wc/v1/update-paid-status/1?consumer_key=ck_XXXX&consumer_secret=cs_XXXX

Response:

The response will be a JSON object indicating the success or failure of the operation.

Example Response:

{
  "message": "Paid status updated successfully."
}

Error Handling #

The API uses standard HTTP status codes to indicate the success or failure of requests. In case of an error, the response will include a JSON object with an error message.

Example error response:

{
  "code": "not_found",
  "message": "Record not found.",
  "data": {
    "status": 404
  }
}

Rate Limiting #

Please be aware that rate limiting may be in place to prevent abuse of the API. If you encounter rate limiting, you will receive a 429 (Too Many Requests) status code. In such cases, please wait before making additional requests.

Support #

If you encounter any issues or have questions about using this API, please contact the site administrator for assistance.